Errors

Error envelope

Every error response carries a JSON body in the same shape:

{
  "error": {
    "code": "<machine-readable>",
    "message": "<human-readable>",
    "request_id": "<uuid>",
    "correlation_id": "<uuid>"
  }
}

Branch on error.code, not on the message text. Include request_id when contacting support. Both ids are also returned as the X-Request-ID and X-Correlation-ID headers.

Standard error codes

HTTP status code summary

400	Bad Request	Malformed query parameters or path values
401	Unauthorized	No Authorization header
401	Unauthorized	Key invalid, expired, or revoked
403	Forbidden	Key valid but lacks the required dataset scope
404	Not Found	Resource not found
406	Not Acceptable	Pinned schema version not supported
410	Gone	Pinned schema version has been withdrawn
422	Validation error	Unknown sources key, or a parameter that failed validation
429	Too Many Requests	Rate limit exceeded; Retry-After set
500	Internal Server Error	Server-side error; request_id required for support
503	Service Unavailable	Temporarily unavailable; retry with backoff

Error types

bad_request	Malformed query parameters or path values
auth_missing	No Authorization header
auth_invalid	Key invalid, expired, or revoked
scope_missing	Key valid but lacks the required dataset scope
not_found	Resource not found
schema_unsupported	Pinned schema version not supported
schema_withdrawn	Pinned schema version has been withdrawn
validation_error	Parameter failed a type or enum check
invalid_source	Unknown or empty sources key
rate_limited	Rate limit exceeded; Retry-After set
internal	Server-side error; request_id required for support
unavailable	Temporarily unavailable; retry with backoff

Mid-stream errors

A streaming response sends its 200 OK before the body, so a failure partway through cannot change the HTTP status. The error envelope arrives in-band as the final record, with error.code set to upstream_unavailable:

{"id":"eu-fsf-1003", ...}
{"id":"un-sc-6907993", ...}
{"error":{"code":"upstream_unavailable","message":"sanctions stream interrupted","request_id":"…","correlation_id":"…"}}

In the default json format the envelope is the last element of the array, and the array still closes normally. In jsonl it is the last line.

Always inspect the last record of a stream. If it is an error envelope, the records before it are valid but the dataset is incomplete. Retry the pull.

See Streaming and snapshots for recovery options after an interrupted stream.