Docs·Public Data API
Public Data API
Errors
Every stable error code, the condition that raises it, and what the caller should do about it.
Errors#
Every failure carries a stable code. Branch on that, not on the status: a code is part of the contract and adding one is an ordinary change, while changing one is a breaking change to whatever is already branching on it.
| Code | Status | Meaning |
|---|---|---|
API_V1_BAD_PARAMETER | 400 | A path or query parameter is not the shape the endpoint accepts. details names the parameter, what arrived and what is accepted |
API_V1_BAD_CURSOR | 400 | A cursor did not decode, or was minted for a different query. details carries both query fingerprints |
API_V1_UNSUPPORTED_FORMAT | 400 | ?format= asked for something other than json or csv |
API_V1_NOT_FOUND | 404 | The subject of a single-resource route is not in the index. The message names the factories in scope and points at /api/v1/health |
API_V1_DATA_NOT_STORED | 404 | The request asks for data we have not stored — today, a from/to range on /stats/daily or /fees entirely before the first stored day or after the newest indexed block’s day. Never fetched on demand. details: requestedFrom, requestedTo, storedFirstDay, storedThroughDay, asOfBlock, table. Retry with a range that overlaps the stored days |
API_V1_RATE_LIMITED | 429 | The tier’s window is full. The exact wait is in the message and the details |
API_V1_READER_SHAPE_UNEXPECTED | 500 | A query ran and what came back is not the shape the view declares — for instance a quantity that arrived as a float. Refused rather than published |
API_V1_READER_UNREACHABLE | 503, or 500 | The read-only connection could not be opened or a query failed (503); an unclassified failure wrapped at the endpoint boundary answers 500, with the original message in details.underlying |
API_V1_READER_URL_MISSING | 503 | The reader connection variable is not set in this environment |
API_V1_READER_URL_IS_WRITER | 503 | The reader is unset while the writer is set. The API refuses to fall back onto the writer rather than working today and breaking the day a replica is introduced |
API_V1_READER_DRIVER_MISSING | 503 | The Postgres driver is not installed. The message names the package and the command |
API_V1_FRESHNESS_CHECKPOINT_MISSING | 503 | The indexer has written no checkpoint, so no figure can carry an asOfBlock — and no figure is published without one |
A failure is sent with Cache-Control: no-store. A cached 503 outlives the fault that caused it, so an RPC that recovers in two seconds would otherwise keep serving “unreachable” for the rest of the window.