Errors
Statuses
| Status | Meaning |
|---|---|
| 200 | Success |
| 401 | Missing or invalid API key |
| 402 | Account suspended (subscription canceled or payment failed) |
| 429 | Rate limit exceeded, or the monthly quota is exhausted on a key that stops at its quota rather than billing overage. `retry-after` says how long to wait. |
Plus the ones any HTTP service can return:
| Status | Means | Retry? |
|---|---|---|
404 | No article with that id. | No — the id is wrong or the article was removed. |
408 | The request exceeded the server's own time budget. | Yes, but narrow it first — see below. |
413 | Request body too large. Only reachable on the MCP endpoint. | No. |
503 | The query tier could not answer — no shard covering your range responded. | Yes, with backoff. |
Retrying
Three of these are worth retrying, and each wants a different wait.
429, rate limit
Transient. retry-after is 1, because the bucket refills continuously — wait a second and
the same request works. Do not exponentially back off from one second to a minute; you will be idle for 59 seconds
you had paid for. Rate limits and backoff has a correct client.
429, quota
Not transient. The monthly allowance is exhausted and the key stops at its quota rather than billing overage, so
retrying will not help until the period resets — retry-after says how many seconds that is, and it may
be days. Distinguish the two by reading x-quota-remaining: it is 0 for this case.
503
Every shard covering your time range failed to answer. Deliberately not reported as zero results: an agent
that reads "no matches" when the fleet is degraded concludes the story does not exist. Retry with backoff, and
narrow the range — a tighter from/to asks fewer shards and is likelier to succeed.
408
A relevance query over a wide time range has to visit every shard overlapping it. If you are hitting this, the fix is almost always a narrower window rather than a longer client timeout — see Time windows.
What is not an error
- Zero results.
200with an emptyresultsarray. Usually an exact filter value that does not exist — check it against a facet. - Fewer results than expected. Check
from_clamped: your plan may have narrowed the window. Archive depth. - An unknown query parameter. Ignored rather than rejected, so a typo in a filter name silently widens your query instead of failing. Check names against Filters and signals.
On MCP
The same conditions, but two of them are reported as tool errors rather than as statuses, because an HTTP error on a tool call reads to a client as a server that has gone away. MCP errors has the mapping and the exact payloads.