Skip to main content

Errors and request tracing

Identify the failure stage before correcting, querying or resending.

Read the error envelope

Standard /v1 model endpoints use the selected protocol’s error format. Legacy endpoints, console queries and financial APIs may use different envelopes. Do not force every response through one parser.

Illustrative OpenAI shape:

json
{"error":{"type":"invalid_request_error","message":"Invalid request"}}

Illustrative Anthropic shape:

json
{"type":"error","error":{"type":"invalid_request_error","message":"Invalid request"}}

These examples show structure only. Use actual machine codes and fields rather than matching the illustrative message text.

Status and next action

HTTP statusCommon causeNext action
400Invalid format, parameter or output budgetCorrect the payload against the selected configuration
401Missing, invalid or revoked credentialCheck the key; do not substitute a browser session
402Insufficient balance, quota or membership entitlementCheck the credential’s funding source; do not raise budgets automatically
403Missing scope, model permission or identity requirementVerify permission and availability
404Missing/disabled model or unavailable compatibility endpointRefresh the catalog and check identifiers and path
409Changed price version, idempotency or contract conflictReconfirm price or inspect the original operation; do not evade with random keys
429Rate, concurrency or window limitRespect applicable Retry-After; distinguish unaccepted from unknown requests
503Billing, identity, provider or dependency unavailableRead the machine code and status; preserve request identifiers

Retry-After describes waiting, not proof that a paid POST is safe to replay. Resend only after confirming non-acceptance and deciding to continue. Query uncertain outcomes first. See streaming errors.

Retain the right identifiers

IdentifierPurpose
X-Request-IDTransport correlation and troubleshooting
X-Acosmi-Request-IdReturned consumption identifier for original costs
Provider/task/operation IDSpecific upstream or business operation; not interchangeable with the above

Inspect the original request and financial status in My requests. Do not log plaintext keys, cookies or sensitive inputs. A timeout does not prove non-execution; missing usage is not free usage.

Other Acosmi SDK operations distinguish HTTPError, NetworkError, BusinessError and CompliancePollError. See the SDK reference.