Errors

When an API request fails, badges.ninja returns a JSON error response with an appropriate HTTP status code.

Error Format

All errors follow this structure:

{
  "error": "description of what went wrong"
}

Status Codes

Code	Meaning	When It Happens
400	Bad Request	Missing or invalid parameters, plan-limit or quota reached, feature requires a higher plan, or not authorized — all validation failures return 400
402	Payment Required	Reserved for credit exhaustion. The badges API does not currently deduct credits, so this code is never returned in practice
404	Not Found	The requested resource does not exist
500	Internal Server Error	An unexpected error occurred on the server

There is no 403 or 429: authorization failures return 400 ("not authorized") and there is no application-layer rate limiting.

Common Errors and Solutions

Missing required parameters

{ "error": "missing required parameters: name, url, email" }

Solution: Include all required parameters in your request body. Check the endpoint documentation for the full list.

Invalid email

{ "error": "invalid email" }

Solution: Provide a valid email address in the format user@domain.com.

Invalid URL

{ "error": "invalid URL" }

Solution: Provide a full URL including the protocol, e.g. https://example.com.

Name too short

{ "error": "name must be at least 3 characters" }

Solution: Use a longer name. Issuer names require at least 3 characters. Recipient names require at least 5 characters.

Issuer not verified

{ "error": "issuer must be verified before creating badges" }

Solution: Verify the issuer first. Check the issuer email for the verification link, or use the Verify Issuer endpoint.

Monthly award quota reached (400)

{ "error": "monthly award quota reached (100/100 on the free plan) — wait for the 1st of next month or upgrade your plan" }

Solution: You have used all the awards included in your plan for the current calendar month (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). The counter resets at 00:00 UTC on the 1st of each month; upgrade your plan for a higher allowance. See Plans & Billing.

Plan limit reached (400)

{ "error": "issuer limit reached (1/1 on the free plan) — delete an issuer or upgrade your plan" }

The badge cap uses the same shape:

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

Solution: You have hit your plan's cap on issuers or badges. Delete an unused resource or upgrade your plan.

Blockchain requires Pro (400)

{ "error": "blockchain verification requires the Pro plan" }

Solution: The blockchain parameter is only available on the Pro plan. Upgrade to enable it.

Unsupported blockchain

{ "error": "unsupported blockchain, only 'matchain' is supported" }

Solution: Currently only matchain is supported as a blockchain parameter.

Resource has dependencies (400)

{ "error": "issuer has 3 badge(s) linked — delete the badges first" }

Solution: Delete all badges linked to the issuer before deleting the issuer. Similarly, delete all awards under a badge before deleting the badge.

Not authorized (400)

{ "error": "not authorized" }

Authorization failures are validation errors, so they return 400 (not 401 or 403).

Solution: You can only modify resources you own. Make sure you are using the correct API key.

HTML in share text

{ "error": "HTML tags are not allowed" }

Solution: Share text must be plain text. Remove any HTML tags from the text parameter.