Structured errors#
Failures use application/problem+json with type, title, status, code, detail and request_id. Use code for integration decisions and request_id for support. Do not depend on title or detail wording. Handle unsuccessful HTTP responses before reading success fields.
What each status means#
- 400: invalid parameter, schema or cursor. Correct the input before retrying.
- 401: missing, invalid or revoked credential.
- 403: unauthorized access/origin. Check your channel; do not supply internal secrets.
- 404: identifier not found in the catalog.
- 429: quota or request-rate limit. Honor Retry-After and check your plan.
- 500 or 503: internal failure or temporary unavailability. Use bounded retries and contact support if it persists.
Retries without amplifying failures#
Configure timeouts, maximum attempts and backoff with jitter. Honor returned Retry-After and avoid aggressive retries when a monthly quota is exhausted. Authenticated requests can count toward usage even when the response is an error; limits depend on channel and plan.