Errors & rate limits
Errors are JSON with a stable code and a human message. Handle the codes, show the message.
Error format#
4xx
{ "error": { "code": "rate_limited", "message": "Rate limit of 5 requests/second exceeded.", "retry_after_ms": 412 } }Codes#
| Field | Type | Description |
|---|---|---|
| 400 invalid_request | Body or query did not match the documented shape. | |
| 400 invalid_name / invalid_domain | Finder input could not be parsed. | |
| 401 unauthorized | Missing, malformed, invalid or revoked key. | |
| 402 insufficient_credits | Not enough credits. Includes available (and required for lists). | |
| 403 ip_not_allowed | Key is pinned to trusted IPs and this request came from elsewhere. | |
| 403 origin_not_allowed | Public key used from an origin that is not allowed. | |
| 403 public_key_not_allowed | Public key called an endpoint other than POST /v1/verify. | |
| 404 not_found | No such bulk job for this account. | |
| 413 payload_too_large | Body over 4 KB (single) or 5 MB (bulk). | |
| 429 rate_limited | Per-key limit exceeded. Wait retry_after_ms and retry. |
Rate limits#
| Field | Type | Description |
|---|---|---|
| Free | 5 req/s | 2 concurrent list workers · 250 credits / month |
| Starter | 10 req/s | 5 concurrent list workers · 10,000 credits / month |
| Growth | 25 req/s | 10 concurrent list workers · 50,000 credits / month |
Limits are per API key over a sliding one-second window. Your current limits are on Settings › Limits.
Related