Core concepts

Errors

Interpret validation, authentication, rate-limit, and upstream failures.

On this page

Use HTTP status and the documented response schema together. Do not parse human-readable messages to drive retry behaviour.

Error classes

Validation — correct the request before retrying.
Authentication — verify the key and application scope.
Rate limit — wait according to response metadata.
Upstream — retry only when documented and preserve the request ID.

Never expose raw upstream payloads directly to end users.

V2 errors expose a stable code, safe message, and request ID. Capture the code for application logic and the request ID for diagnosis. Treat fields in the API Reference as canonical; do not infer internal provider details from the public message.

Decide once

Centralize classification in your API client so every worker applies the same policy. The result should answer whether to correct input, stop and alert, wait for rate capacity, retry within a deadline, or show a declared unavailable state.

Class	Default client action
Validation or authentication	Stop; correct the request or credential
Product access, credits, or availability	Stop the operation and surface an account or product state
Rate limit	Wait according to documented response metadata and coordinate callers
Privacy or not found	Preserve the product-specific state; do not retry unchanged
Transient upstream or capacity	Retry only if the operation and workflow budget permit
Unexpected error	Preserve evidence, fail safely, and avoid blind retry storms

Continue with Retries & timeouts, Request IDs, and Troubleshooting.