Errors

Branch on the type, then the code. Messages may change.

json
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_invalid",
    "message": "limit must be between 1 and 100.",
    "param": "limit",
    "requestId": "9f1c2e4a-…",
    "docUrl": "https://gloom.sh/datasets/docs/errors#parameter_invalid"
  }
}
  • param names the parameter or header at fault, or is null.
  • Errors cost nothing. A 404 or 503 after the charge is refunded.
  • A 401 without a key carries WWW-Authenticate: Bearer realm="Gloom Datasets"; a refused key adds error="invalid_token".
  • For support, quote Request-Id.

Types

StatusTypeRetry-After
400invalid_requestNo
401authenticationNo
402planNo
403permissionNo
404not_foundNo
429rate_limitYes
503api_errorYes
What each code means17
parameter_unknown400
A parameter this route does not take. param names it.
parameter_missing400
A required parameter is missing. param names it.
parameter_invalid400
A parameter has the wrong type, format or range.
parameter_repeated400
A parameter was sent more than once.
cursor_invalid400
The cursor does not belong to this route and query. Start again without it.
body_invalid400
The JSON body is missing, too large or does not match.
version_invalid400
The Gloom-Version header names no published version.
missing_key401
No key was sent. Use Authorization: Bearer gds_...
invalid_key401
The key is unknown or revoked.
wrong_key401
A Gloom Pro or News key was sent. Datasets keys start gds_.
plan_required402
The account has no plan. Choose one to read data.
dataset_not_included402
The plan does not include this dataset or depth.
key_disabled403
The key or its account is disabled, or the email is unverified.
not_found404
No record has this id.
rate_limited429
The key is over its per-minute credits. Wait Retry-After.
credits_exhausted429
The period's credits are spent. They renew with the period.
unavailable503
The stored dataset cannot be read right now. Retry later.