Errors and rate limits
Handle API v2 error envelopes, status codes, scope failures, and retry timing.
Last updatedAPI v2 returns machine-readable errors in one envelope:
{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"details": {
"issues": []
}
}
}Branch application logic on error.code, not on human-readable message. The wording can improve without changing the condition. details is optional and varies by error.
Status codes
| Status | Meaning |
|---|---|
200 OK | A read or completed action returned data. |
201 Created | A resource was created. |
202 Accepted | Work was accepted and can complete asynchronously. Read the returned state. |
204 No Content | The action succeeded without a JSON body. |
400 Bad Request | Input validation failed. Inspect error.details.issues when supplied. |
401 Unauthorized | Credentials are missing or cannot be authenticated. |
403 Forbidden | The key, API switch, scope, subscription, plan, trial, or feature blocks access. |
404 Not Found | The route or requested community resource does not exist. |
409 Conflict | Current state conflicts with the write, such as a duplicate blacklist entry. |
429 Too Many Requests | Wait for the response’s retry interval. |
500 Internal Server Error | A service error prevented the request. Reconcile state before retrying a write. |
Each generated endpoint page lists the responses declared by its current route schema.
Important error codes
Authentication and entitlement codes include missing_credentials, api_disabled, key_disabled, legacy_key_unsupported, insufficient_scope, entitlement_required, api_access_unavailable, and feature_unavailable. Routing and validation can return route_not_found and validation_failed.
An insufficient_scope response also sets WWW-Authenticate with the required scope and includes required and granted scopes in details.
Rate limiting
Rate limits protect both unauthenticated traffic and authenticated keys. The values are deployment-configurable, so clients must not assume a fixed number from old examples.
A limited response uses 429 rate_limit_exceeded, sets Retry-After in seconds, and includes values such as:
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too Many Requests",
"details": {
"limit": 100,
"remaining": 0,
"resetMs": 30000
}
}
}The numbers above illustrate the shape only. Always use the values in the actual response.
Wait at least Retry-After, add jitter when many workers share a key, reduce polling, and avoid retry storms. A 429 does not justify rotating keys.
For a diagnostic checklist, see API request errors.