Skip to documentation content
Dataset APIDocs
Back to website
FIEN

Errors and retries

Classify failures and retry only when the operation is safe.

9 min Updated 2026-08-15Docs version 1.0
In this guide
  1. 1Read the error object
  2. 2Keep request IDs
  3. 3Retry selectively
In this guide
  1. 1Read the error object
  2. 2Keep request IDs
  3. 3Retry selectively

Standard error object

JSON
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_01J4N7"
  }
}

Classify before retrying

StatusMeaningAction
400Request validation failedFix the request; do not retry unchanged
401Authentication required or invalidRepair or rotate the credential
404Dataset, release, or build not foundVerify the stable identifiers
429Rate limit exceededWait for Retry-After, then retry with jitter
500Temporary service failureRetry safe reads with exponential backoff

Treat methods differently

GET operations are safe to retry after transient network, 429, or 5xx failures. POST /datasets/{dataset_id}/query is a read-like operation and can be retried with the same body. POST /builds creates work and has no public v1 idempotency key, so reconcile an ambiguous result before resubmitting.

Keep incident context

  1. 1
    Log request_id when present
  2. 2
    Log the route template rather than secrets or full URLs
  3. 3
    Keep dataset, release, and build IDs
  4. 4
    Record attempt count and elapsed time
  5. 5
    Separate permanent validation failures from transient availability failures
Was this page helpful?