Errors
Status codes returned by the Data API and what they mean.
The Data API uses HTTP status codes to signal success and failure. The response body for an error is always:
{ "detail": "Human-readable explanation." }Tool-level "miss" conditions — e.g. a company is not in our database, or a
filing has no revenue-by-geography rows — are returned as HTTP 200 with
an error field in the JSON. Clients should inspect error after parsing
successful responses.
Status codes
| Code | Meaning | What to do |
|---|---|---|
200 OK | Request succeeded. Body may still contain a tool-level error. | Inspect error before treating the body as data. |
400 Bad Request | Invalid input. | Read detail, fix the request, do not retry. |
401 Unauthorized | Missing or invalid API key. | Set the Authorization header. Rotate a leaked key. |
403 Forbidden | Plan does not include Data API access. | Upgrade to Pro / API / Custom. |
404 Not Found | Path does not exist (typo, wrong version). | Check the API Reference. |
422 Unprocessable Entity | Body failed Pydantic validation. | Compare your JSON to the endpoint schema. |
429 Too Many Requests | Rate limit or monthly quota exceeded. | Respect Retry-After; see Rate limits. |
500 Internal Server Error | Unexpected upstream failure. | Safe to retry with backoff. |
502 Bad Gateway | A backend (Weaviate, EDGAR) was unreachable. | Retry with backoff. |
504 Gateway Timeout | A backend took too long to respond. | Retry with backoff, narrow the query. |
Idempotency and retries
All Data API endpoints are read-only. Every successful response is a
function of the request parameters at the moment of the call. Retries are
always safe — but use exponential backoff for 429 and 5xx codes so you
do not amplify a temporary upstream outage.
"No data" vs. "error"
Some endpoints can succeed in the protocol sense (200) while still telling you there is nothing to return:
{ "error": "No profile found", "company": "UnknownCo", "locale": "en" }This separation lets clients tell the difference between the company
exists but we have nothing on file (200 + error) and the request was
malformed (4xx + detail).