> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> HTTP status codes returned by the Blockworks API, the error envelope, every error message the Data API sends, and how to resolve each one.
The Blockworks API uses conventional HTTP status codes. In general:
* `2xx`: the request succeeded.
* `4xx`: the request failed because of something in the request (a bad parameter, a missing key, a
model you cannot access).
* `5xx`: something went wrong on our side. These are rare.
## The error envelope
Errors use the same envelope as successful responses. On failure, `error` holds a human-readable
message and `data` is `null`.
```json theme={null}
{
"error": "unknown query parameter \"marketCap\"",
"data": null
}
```
Check `error` before reading `data`. A non-`null` `error` always accompanies a non-2xx status code.
Branch on the status code, and treat the message as a hint for humans: the wording can change.
## Status codes
| Code | Status | Meaning |
| ----- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK | The request succeeded. This includes a timeseries request whose key matched no series: it returns `200` with an empty `points` array, never `404`. |
| `400` | Bad Request | The request was malformed: an unrecognized query parameter, an invalid filter or window value, too many series, or an unsupported `acceptFormat`. |
| `401` | Unauthorized | The model requires authentication and no API key was provided. |
| `403` | Forbidden | Either the key is not valid (`Forbidden`), or it is valid but lacks access to this model: it needs a paid plan, a specific permission, or internal access. |
| `404` | Not Found | The model slug or granularity does not exist, a tabular row identifier matched nothing, or the multi-series endpoint was called without `series` on a model that requires it. |
| `500` | Internal Server Error | Something failed on our side. These are rare, so please report them. |
| `504` | Gateway Timeout | The request took longer than expected to process. Retry, ideally with a narrower time window or page size. |
## Every error message
The full set of messages the Data API sends, with the request that triggers each one.
| Status | `error` | Trigger |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `unknown query parameter "granularity"` | Any query parameter the endpoint does not declare, including a filter without its operator suffix (`?name=` instead of `?nameEq=`) or a parameter that belongs in the path. |
| `400` | `unrecognized timeframe "1y"` | A `timeframe` outside the grammar. `1y` and `1M` are the usual culprits: use `365d`, `52w`, `ytd`, or a calendar year such as `2025`. |
| `400` | `cannot combine timeframe with start/end` | Both window styles in one request. |
| `400` | `invalid start: expected RFC3339, unix seconds, or YYYY-MM-DD, got "yesterday"` | `start` or `end` in another format. |
| `400` | `start 2026-02-01 00:00:00 +0000 UTC is after end 2026-01-01 00:00:00 +0000 UTC` | A window that ends before it starts. |
| `400` | `invalid bounds "yes": must be true or false` | `bounds` is a boolean. |
| `400` | `invalid acceptFormat "xml": expected one of json, csv, jsonl` | An unsupported output format. |
| `400` | `unknown selection field "tvl"` | A `selections` value that is not a column or metric `field` of the model. |
| `400` | `too many series requested: 21 exceeds the maximum of 20` | More than 20 keys in `series`. |
| `400` | `duplicate series key "b204e48e-..."` | The same key twice in `series` (compared case-insensitively). |
| `400` | `no series keys specified in the series parameter` | `series=` present but empty. |
| `400` | `filter "circulatingMarketcapGte": invalid float64 value "1b": ...` | A filter value that does not parse as the column's type. |
| `400` | `pageSize 5000 exceeds maximum of 1000` | `pageSize` above 1000. |
| `400` | `unknown sortBy field "nope"` | `sortBy` names a column that is not sortable. |
| `401` | `this model requires authentication` | A gated model without an API key. |
| `403` | `Forbidden` | An API key that is not valid. This message comes from the gateway, not the API. |
| `403` | `this model requires a paid subscription` | A valid key on a plan that does not include the model. |
| `404` | `no timeseries model "network" with granularity "1h"` | An unknown timeseries slug, or a granularity the model does not support. The same message covers both today; an upcoming release splits it into `no timeseries model "..."` and `model "..." does not support granularity "..." (supported: ...)`. |
| `404` | `the all-series endpoint is not available for model "blockchains"; request specific series via ?series or a series-key path` | The multi-series endpoint without `series` on a model whose catalog entry has `allowAllSeries: false`. |
| `404` | `tabular model "nope" not found` | An unknown tabular slug. |
| `404` | `no row found matching "not-a-chain"` | A row identifier that matched neither the primary key nor an identifier column. |
## Common errors
### Unknown query parameter (400)
The API rejects any query parameter it does not recognize rather than silently ignoring it. This is
deliberate: a typo in a filter name would otherwise return unfiltered data.
```json theme={null}
{
"error": "unknown query parameter \"marketCap\"",
"data": null
}
```
Filters always carry an explicit operator suffix: `marketCapGte`, not `marketCap`. There is no
bare-field form. Check the model's supported filters in the
[catalog](/getting-started/concepts/catalog) or on the endpoint's reference page.
### Invalid filter value (400)
The value must parse as the column's type.
```json theme={null}
{
"error": "filter \"circulatingMarketcapGte\": invalid float64 value \"1b\": ...",
"data": null
}
```
Dates accept RFC3339, unix seconds, or `YYYY-MM-DD`.
### Invalid time window (400)
`timeframe` and `start`/`end` are mutually exclusive, and each has its own accepted formats.
```json theme={null}
{
"error": "cannot combine timeframe with start/end",
"data": null
}
```
```json theme={null}
{
"error": "unrecognized timeframe \"1y\"",
"data": null
}
```
There is no year or month unit in relative windows. Use `365d`, `52w`, `ytd`, or a calendar
period such as `2025` or `2025-06`. See
[Granularity & time ranges](/getting-started/concepts/granularity) for the full grammar.
### Too many series (400)
A single `?series=` request may name at most 20 series keys, and may not repeat one.
```json theme={null}
{
"error": "too many series requested: 34 exceeds the maximum of 20",
"data": null
}
```
### Authentication required (401)
The model is gated and the request carried no API key.
```json theme={null}
{
"error": "this model requires authentication",
"data": null
}
```
Confirm the `X-Blockworks-API-Key` header is present and the key is current. See
[Authentication](/getting-started/authentication).
### Invalid key (403)
The key itself was rejected. The body is the gateway's, not the API's envelope message.
```json theme={null}
{
"error": "Forbidden",
"data": null
}
```
Check for a copy-paste error or a rotated key. A public model still returns `403` when the key
sent with the request is invalid, so remove a stale key rather than leaving it in place.
### Insufficient access (403)
Your key is valid, but the model is above your access tier.
```json theme={null}
{
"error": "this model requires a paid subscription",
"data": null
}
```
Read `access.tier` for the model from the [catalog](/getting-started/concepts/catalog) to see what
it requires. If you believe you should have access, contact support.
### Not found (404)
Returned for an unknown model slug, an unsupported granularity for that model, or a tabular row
identifier with no matching row.
```json theme={null}
{
"error": "no timeseries model \"asset-price\" with granularity \"1n\"",
"data": null
}
```
Some timeseries models have too many series to return at once. For those, the all-series endpoint is
unavailable and you must name the series you want:
```json theme={null}
{
"error": "the all-series endpoint is not available for model \"asset-price\"; request specific series via ?series or a series-key path",
"data": null
}
```
The catalog's `allowAllSeries` flag tells you which models support the all-series form.
A timeseries request never returns `404` for an unknown series key. It returns `200` with
`"points": []` and no `entity`. If a series comes back empty, check that the key is the lookup
table's primary key (a UUID for assets and networks), not a slug or a symbol. See
[Finding an id](/api-reference/data-api/discovery/finding-an-id).
### Server errors (500)
These indicate a problem on our side. We monitor for them, but reports help. Include the
`X-Request-Id` response header from the failing call when you contact support; it lets us find the
exact request.