Errors

HTTP status codes and the exact error response shapes the Data API returns — with an interactive lookup.

The API uses standard HTTP status codes. 2xx means success; anything else carries an error body, and the body shape depends on which layer failed. Pick a status code below to see when it happens, exactly what comes back, and how to handle it.

When it happens

The request body is malformed before the query even runs — most often limit or offset is not a number.

Response body

{  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",  "title": "One or more validation errors occurred.",  "status": 400,  "errors": {    "$.limit": [      "The JSON value could not be converted to System.Int32."    ]  },  "traceId": "00-ffc84beb047191d9…-00"}

How to handle

Send valid JSON with the right types (limit and offset are numbers, not strings). The errors object names each offending field by its JSON path.

Where the shape comes from

{ message, error_code } — the data layer (e.g. a 404 for a missing table).
{ error, error_code } — the application error object documented in the OpenAPI spec.
error code: NNN (plain text) — a gateway-level 5xx that never reached the application.
RFC 9110 problem document — request validation (400 / 422), with bad fields under errors.

When present, read error_code for a stable machine-readable reason and fall back to the human message.

The one that surprises people

A malformed filter or an unknown column returns 502, not 400. The filter is passed straight to the query engine, so the engine — not the request validator — is what rejects it. So:

Bad operator (._gte) or bad column name → 502, body error code: 502.
Bad value type (limit: "abc") → 400, the RFC problem document above.

See Querying for the exact filter grammar.

Handling errors

Check the status code first, then parse the body by the shapes above.
404 is normal while browsing — a namespace may simply have no such table.
For 502 / 503 / 504, retry with backoff — but first rule out a bad query (they are the same code the engine returns for an invalid filter).

Querying tables

The full filter operator and _and/_or grammar.

Recipes

Copy-paste solutions to common tasks.

The one that surprises people

Handling errors

Querying tables

Recipes

See also

On this page