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.

Credential quota reached (400)

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

Solution: You have used your full annual credential pool (Free: 1,200/year, Starter: 12,000/year, Pro: 120,000/year). The pool resets on your account's registration anniversary — not on a calendar-month boundary. Upgrade your plan for a higher allowance. See Plans & Billing.

Plan limit reached (400)

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

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.

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 credentials 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.