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
402	Payment Required	Monthly award quota reached or feature requires a higher plan
403	Forbidden	Plan-limit reached (e.g. issuer or badge cap)
404	Not Found	The requested resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	An unexpected error occurred on the server

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

{ "error": "monthly award quota reached" }

Solution: You have used all the awards included in your plan for this billing period (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Wait for the next reset or upgrade your plan. See Plans & Billing.

Plan limit reached

{ "error": "issuer limit reached for your plan" }

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

Blockchain requires Pro

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

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

Unsupported blockchain

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

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

Resource has dependencies

{ "error": "issuer has badges and cannot be deleted" }

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

Not authorized

{ "error": "not authorized" }

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.