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 malformed, revoked or expired, or the endpoint needs one and none was sent | Check the header, or create a new key. Public accounts need no key |
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 and 403 are not interchangeable.401 means we do not know who you are. 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.No plan error
The API is included in every plan, so a valid key is never turned away for the plan it is on. The plan only decides whether the attribution is required and how many requests per minute the key gets.
When a key is not needed
Search, one published account and its widget snippet work with no key. A 401 on those
endpoints means a key was sent and is wrong: remove it or fix it. The endpoints about your
own accounts always need one.
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.
The limit is per key: 30 requests per minute on the free plan, 120 on Pro and Ultra. 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.