Errors

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.

{
  "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.

{
  "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 or on the endpoint’s reference page.

Invalid filter value (400)

The value must parse as the column’s type.

{
  "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.

{
  "error": "cannot combine timeframe with start/end",
  "data": 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 for the full grammar.

Too many series (400)

A single ?series= request may name at most 20 series keys, and may not repeat one.

{
  "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.

{
  "error": "this model requires authentication",
  "data": null
}

Confirm the X-Blockworks-API-Key header is present and the key is current. See Authentication.

Invalid key (403)

The key itself was rejected. The body is the gateway’s, not the API’s envelope message.

{
  "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.

{
  "error": "this model requires a paid subscription",
  "data": null
}

Read access.tier for the model from the 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.

{
  "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:

{
  "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.

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.

Getting Started

Discovery

Concepts

Market Data

Blockchains

Projects & Protocols

Real World Assets

Institutional

Fundraising

Social & Mindshare

News & Research

Token Transparency Framework

Charts

The error envelope

Status codes

Every error message

Common errors

Unknown query parameter (400)

Invalid filter value (400)

Invalid time window (400)

Too many series (400)

Authentication required (401)

Invalid key (403)

Insufficient access (403)

Not found (404)

Server errors (500)

​The error envelope

​Status codes

​Every error message

​Common errors

​Unknown query parameter (400)

​Invalid filter value (400)

​Invalid time window (400)

​Too many series (400)

​Authentication required (401)

​Invalid key (403)

​Insufficient access (403)

​Not found (404)

​Server errors (500)

The error envelope

Status codes

Every error message

Common errors

Unknown query parameter (400)

Invalid filter value (400)

Invalid time window (400)

Too many series (400)

Authentication required (401)

Invalid key (403)

Insufficient access (403)

Not found (404)

Server errors (500)