Reference for all API error codes and how to handle them.
HTTP status codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 202 | Accepted - Batch or file job queued |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 402 | Payment Required - Out of credits, or plan renewal needed |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Endpoint doesn't exist |
| 413 | Payload Too Large - Request body exceeds the limit |
| 429 | Too Many Requests - Rate limited |
| 500 | Server Error - Try again later |
| 503 | Service Unavailable - Retry with backoff |
| 504 | Gateway Timeout - Upstream verification timed out |
Error response format
Errors use the same envelope as successful responses, with success: false and the detail under error. Branch on error.code rather than matching error.message, which is free text. Quote error.request_id when contacting support.
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid email format",
"request_id": "89eac422-6b08-4d18-986b-ab3e1ed3aa57"
}
}Common error codes
| HTTP | error.code | Solution |
|---|---|---|
| 400 | BAD_REQUEST | Check the request body and email format |
| 401 | UNAUTHORIZED | Send a valid key in X-API-Key |
| 401 | API_KEY_SUSPENDED / API_KEY_REVOKED | Issue a new key in the dashboard |
| 402 | INSUFFICIENT_CREDITS | Add more credits |
| 402 | PAYMENT_REQUIRED | Upgrade or renew your plan |
| 403 | FORBIDDEN | Access denied for a reason the codes below do not cover |
| 403 | INSUFFICIENT_SCOPE | The key is valid but not scoped for this route — issue one that is (an app connected by signing in: connect it again asking for the scope as well as the ones it already has — unless the message says a connected app can never be given it; then use an API key with every scope the message names, or have the account owner act in the dashboard) |
| 403 | PLAN_UPGRADE_REQUIRED | Your plan does not include this feature — no key of any scope reaches it |
| 403 | PLAN_LIMIT_EXCEEDED | You are at your plan’s limit for this feature — delete one or upgrade |
| 404 | NOT_FOUND | Check the path and any resource id |
| 413 | PAYLOAD_TOO_LARGE | Reduce the payload, or use the File Upload API |
| 429 | RATE_LIMITED | Back off using Retry-After |
| 500 | INTERNAL_ERROR | Retry; contact support with the request id |
| 503 | SERVICE_UNAVAILABLE | Retry with exponential backoff |
| 504 | GATEWAY_TIMEOUT | Upstream verification timed out; retry |