Errors
Errors come back with a normal HTTP status code and a consistent body:
{
"error": "insufficient_scope",
"detail": "This key is missing the \"public:read\" scope."
}
Status codes
| Code | Meaning | What to do |
|---|---|---|
400 | The request is malformed — a bad date, an unknown sort field | Fix the request; retrying will not help |
401 | The key is missing, malformed, revoked or expired | Check the header, or create a new key |
402 | The key is valid but your plan does not include the API | Activate Pro — the same key starts working again |
403 | The key is valid but lacks the required scope | Create a key with the scope you need |
404 | No such account, or it is private and not yours | Check the slug |
429 | Rate limit exceeded | Wait for Retry-After, then retry |
500 | Something broke on our side | Retry with backoff; if it persists, tell us |
503 | Temporarily unable to serve | Retry with backoff |
401, 402 and 403 are not interchangeable.401 means we do not know who you are.
402 means we know who you are, the key is fine, and your plan does not include the API.
403 means the key is valid but lacks the scope. Only 401 is worth re-authenticating for,
and only 403 is worth creating a new key for.Why a 402 does not revoke your key
When a plan lapses the key is rejected, not revoked. Nothing is deleted, nothing needs to be recreated, and no support ticket is involved: the same key starts working again by itself the moment the plan is active. The plan is read fresh on every request and is never stored on the key, which is why this costs you nothing to recover from.
Why a private account returns 404
Asking for an account that exists but is not yours returns 404, the same as one that does
not exist at all. A 403 would confirm the account is real, which is information the owner
did not publish.
Rate limits
A 429 carries a Retry-After header, in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Wait that long. Retrying immediately, or on a fixed sleep shorter than the header says, will keep you limited for longer than necessary.
Every successful response also tells you where you stand, so you can slow down before you get turned away:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1755864000
Retrying safely
Every endpoint in this API is read-only, so any request can be retried without side
effects. Retry 429, 500 and 503 with exponential backoff. Do not retry 400, 401,
403 or 404 — nothing about them will be different the second time.