David uses conventional HTTP status codes and returns errors as JSON with a single detail field.
Status codes
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:
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.
Response headers on every request:
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.
