Errors

Every error response is a JSON object with at minimum an error field describing what went wrong. Status codes follow HTTP conventions strictly.

Shape

{
  "error": "Human-readable description."
}

Some errors carry additional fields. Quota errors include limit and tier:

{
  "error": "Monthly quota exceeded.",
  "limit": 1000,
  "tier": "FREE"
}

Field	Type	Description
200	OK	Successful response.
400	Bad Request	Malformed parameters — typically an invalid expiry date on key creation, or a malformed signup payload.
401	Unauthorized	Missing key, invalid key, expired key, or unverified email. The error string distinguishes the cases.
403	Forbidden	Suspended account or email not yet verified.
404	Not Found	No product with that EAN. Returned only by the lookup endpoint.
429	Too Many Requests	Monthly quota, per-minute rate limit, or authentication-attempt throttle exceeded. Carries Retry-After for per-minute hits.
500	Server Error	Unexpected error on our side. Safe to retry with exponential back-off.

Field	Type	Description
"Missing API key…"	401	No Authorization header and no X-API-Key header.
"Invalid API key."	401	Header present, but the key was never issued, has been revoked, or does not match.
"API key expired."	401	You set an expiry on this key and that date has passed. Create a new key.
"Email not verified."	403	Account exists but the email confirmation link was never clicked.
"Account suspended."	403	Account has been manually suspended. Contact support.
"Product not found"	404	No EAN match. Note: we do not validate check digits — pass exactly what is printed.
"Monthly quota exceeded."	429	You have used your full plan quota for the calendar month. Upgrade or wait for reset.
"Per-minute rate limit exceeded."	429	Burst rate too high. Honor Retry-After and slow down.
"Too many unauthenticated API requests…"	429	Too many requests without a key from the same client. Send a valid key or try again later.
"Too many invalid API key attempts…"	429	Too many invalid key attempts from the same client. Check your configuration and try again later.

4xx errors: do not retry without changing the request. They will keep failing.
429 per-minute: wait for Retry-After, then retry.
429 monthly: do not retry. Upgrade or wait for the calendar month to reset.
5xx: retry with exponential back-off (e.g. 1s, 2s, 4s, up to ~30s). Stop after a few attempts and surface the failure.