Errors & rate limits

David uses conventional HTTP status codes and returns errors as JSON with a single detail field.

{ "detail": "Scenario not found" }

Status codes

Code	Meaning	Common causes
`200`	Success	The request succeeded.
`400`	Bad request	Invalid parameter combination, for example `interval` other than `day`, or passing both `ticker` and `holding` to `/index-funds`.
`401`	Unauthorized	Missing or invalid `X-API-KEY` header.
`403`	Forbidden	Your key doesn’t have access to the requested resource.
`404`	Not found	Unknown `scenario_id`, ticker, CIK, bank code, or artifact id.
`422`	Unprocessable entity	A request body or query parameter failed validation, for example a `limit` above the allowed maximum, or a malformed filter on a `POST` search endpoint.
`429`	Too many requests	You exceeded your key’s per-minute rate limit.

Validation errors

Validation errors (on POST search endpoints like /financials/search/screener, or on out-of-range query parameters) follow the standard FastAPI shape, listing each offending field:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 10000",
      "type": "value_error"
    }
  ]
}

Handling rate limits

A 429 includes the rate-limit headers so you know your ceiling and when to retry. The window is a rolling 60 seconds.

{ "detail": "Rate limit exceeded" }

Response headers on every request:

Header	Description
`X-RateLimit-Limit`	Requests allowed per minute.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-Account-ID`	Account tied to your key.

Use exponential backoff with jitter on 429 and 5xx responses. Monitor X-RateLimit-Remaining to throttle before you hit the limit.

Empty results vs. errors

David distinguishes “no data” from “error”:

A query for a valid scenario and ticker that simply has no rows returns 200 with an empty list (e.g. {"news": []}).
Non-operating instruments (ETFs, warrants, units) intentionally return empty operating-company datasets (statements, earnings, issuer filings, insider trades) rather than errors. See Ticker universe.
A genuinely unknown scenario_id or ticker returns 404.

Get started

Core concepts

Clients

Guides

Errors & rate limits

Status codes

Validation errors

Handling rate limits

Empty results vs. errors

​Status codes

​Validation errors

​Handling rate limits

​Empty results vs. errors

Status codes

Validation errors

Handling rate limits

Empty results vs. errors