Errors & rate limits

The API uses conventional HTTP status codes and returns a consistent, machine-readable error body so you can handle failures programmatically.

Error envelope

Every error response has the same shape:

Error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A valid email address is required.",
    "requestId": "req_..."
  }
}

code is stable and safe to branch on; message is human-readable and may change. Always log requestId (also returned in the X-Request-ID header) — it lets support trace a specific request.

Status & error codes

HTTP	Code	Meaning
400	`VALIDATION_ERROR`	The request body or parameters were invalid.
401	`UNAUTHORIZED`	Missing or invalid API key / token.
403	`INSUFFICIENT_SCOPE`	The key is valid but lacks the required scope.
403	`INSUFFICIENT_PERMISSION`	The user lacks the required permission.
404	`*_NOT_FOUND`	The resource doesn't exist (e.g. PRODUCT_NOT_FOUND).
409	`INVALID_STATE`	The resource can't change to the requested state.
429	`—`	Rate limit exceeded — slow down and retry.

Rate limits

Public endpoints — product verification, sign-up, counterfeit reports and the contact form — are rate-limited per IP address. Exceeding the limit returns 429 Too Many Requests; wait a moment and retry. Build clients to back off on 429 rather than retrying immediately.

Plan allowances

Separately from rate limiting, each plan includes a monthly allowance of product identities you can create. Paid plans bill a small per-1,000 overage beyond the allowance, so requests aren't blocked — see Pricing.

Retrying safely

GET requests are safe to retry. For writes, retry only on network errors or 5xx responses; a 4xx means the request itself needs changing. Use the requestId when contacting support about a failed call.

NextAPI reference →