Every error is a problem document

The error envelope

Every error from the API, on the JSON path and the CSV path alike, is a problem document with type, title, status, detail and code. The code is what to branch on; codes are never renamed. The type is the code as a URI, https://api.datatactical.group/problems/<code>, and does not change after launch either. A CSV or spreadsheet request never receives a CSV-shaped error. A request with no key:

Request

curl "https://api.datatactical.group/v2/industry/series?areas=22&naics=621&from=2024&to=2025"

Response · replayed 2026-10-05 against vintage 20260913.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json; charset=utf-8
​
{ "type": "https://api.datatactical.group/problems/unauthenticated",
    "title": "Unauthorized", "status": 401,
    "detail": "Provide an API key (Authorization: Bearer …) or a session.",
    "code": "unauthenticated" }

Many problems carry members of their own beside the code, naming what is at fault: parameters on an unknown parameter, cells and cap on a request over the cell ceiling, excluded_fips on a geography refusal, entitlement on a plan refusal, current or superseded_by on a withdrawn vintage, base_url on a key sent to the wrong address. The table at the end of this page lists every code; each endpoint’s page in the reference says which codes that endpoint can send.

A failure after a successful response has started cannot change its status: the connection is cut and the body ends early. A JSON body that does not parse, or a CSV that stops mid-row, is that case; retry the request.

Status codes

400 is a request the API will not interpret. The common ones: an unknown parameter (unknown_parameter), a parameter given twice (repeated_parameter), a spreadsheet-only parameter on a JSON or CSV request (xlsx_only_parameter), both naics and naics_level at once, a summed code list in which one code contains another (with sum=codes), a request over the ceiling of 400,000 cells (cell_cap) or over the series ceiling (series_cap). The rate limits page explains cells; paging is the way past the ceiling.

401 (unauthenticated) is a missing, unknown or expired key. A key that was revoked answers 401 key_revoked instead, with revoked_at, reason and a sentence saying when and why it was revoked.

403 is a valid key that may not do this. geography_excluded when every county in the request is outside the organization’s plan, or when any is and the request says strict=true. plan_required, with an entitlement naming what the plan lacks: api_access for a live key on an organization without the API add-on, past_due while a subscription is unpaid, vintage_access for a prior vintage on a plan without one. session_required for a change to the account made with a key: keys read, and changes are made in the app. wrong_instance for a sandbox key on the live address or a live key on the sandbox, with base_url naming the right one; sandbox_read_only for a sandbox key asked to change anything but a cluster.

404 is an unknown resource, including a cluster that is not your organization’s (cluster_not_found), a vintage that was withdrawn (vintage_withdrawn, with current) or replaced by a correction (vintage_superseded, with superseded_by).

409 is a state conflict on the account surface.

429 always carries Retry-After, in seconds. rate_limited is the per-minute request ceiling; points_exhausted is the organization’s monthly points allowance, and its Retry-After runs to the start of the next UTC month; server_busy (and sandbox_busy in the sandbox) means the service is at capacity and the request was not counted against you.

Retrying

Retry a 429 after the interval given and a 5xx with backoff. Do not retry a 400, 401, 403 or 404 unchanged; the code and the detail say what to change.

Every problem code

The 115 codes the API can send, with the status each comes with and what it means, as the API's OpenAPI document states them. A code is never renamed; a new one may be added, so treat a code you do not know by its status. Each endpoint's page in the reference names the codes it can send.