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 or bearer token	Provide a valid `x-api-key` or `Authorization: Bearer <token>`.
`402`	Payment Required --- insufficient Wallet Credits or missing Generated Data access	Add Wallet Credits for supported pay-as-you-go Om usage, or use a protein UUID with qualifying Generated Data access.
`403`	Forbidden --- access denied	Ensure the authenticated account 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 use a protein UUID with qualifying Generated Data 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 supported pay-as-you-go Om usage or after qualifying Data Generation output exists for the requested protein_uuid. For 5xx responses, use backoff (2s, 4s, 8s, 16s).