Error Handling

Understand and handle API errors effectively.

Common Error Codes

Code	Message	Action
`400`	Bad Request --- invalid parameters or malformed JSON	Fix request format and required params.
`401`	Unauthorized --- missing or invalid API key	Provide a valid x-api-key.
`402`	Payment Required --- insufficient Wallet Credits or missing dataset access	Add Wallet Credits for pay-as-you-go API usage, or restore the required dataset access for data exports.
`403`	Forbidden --- access denied	Ensure your API key user has permission for this resource.
`404`	Not Found	Verify endpoint path and resource identifiers.
`409`	Conflict --- duplicate request still in progress, or job result requested before completion	Reuse the same idempotency key after the in-flight request settles, or wait for the job to succeed before calling enriched result routes.
`429`	Too Many Requests	Slow down or wait before retrying.
`500`	Internal Server Error	Retry with exponential backoff.
`503`	Service Unavailable	Check status page and retry later.
`504`	Gateway Timeout	Reduce limit or stream in smaller chunks.

Best Practices

Check status codes before processing response bodies.
Implement retries with exponential backoff for 5xx errors.
Log the request_id field from response payloads for debugging with support.
Handle HTTP 409 by distinguishing duplicate in-flight launches from result checks made before a job is ready.
Surface HTTP 402 to users so they can add Wallet Credits or restore the required dataset access.

Retry Strategy

Do not retry 400/401/403/404/409 errors without fixing the request. HTTP 402 can be retried after adding Wallet Credits for pay-as-you-go API usage or restoring dataset access (active subscription or qualifying buyout for public datasets; qualifying owned data-generation order for private datasets). For 5xx responses, use backoff (2s, 4s, 8s, 16s).