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:
{"error":{"type":"invalid_request_error","message":"Invalid request"}}Illustrative Anthropic shape:
{"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 status | Common cause | Next action |
|---|---|---|
| 400 | Invalid format, parameter or output budget | Correct the payload against the selected configuration |
| 401 | Missing, invalid or revoked credential | Check the key; do not substitute a browser session |
| 402 | Insufficient balance, quota or membership entitlement | Check the credential’s funding source; do not raise budgets automatically |
| 403 | Missing scope, model permission or identity requirement | Verify permission and availability |
| 404 | Missing/disabled model or unavailable compatibility endpoint | Refresh the catalog and check identifiers and path |
| 409 | Changed price version, idempotency or contract conflict | Reconfirm price or inspect the original operation; do not evade with random keys |
| 429 | Rate, concurrency or window limit | Respect applicable Retry-After; distinguish unaccepted from unknown requests |
| 503 | Billing, identity, provider or dependency unavailable | Read 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
| Identifier | Purpose |
|---|---|
X-Request-ID | Transport correlation and troubleshooting |
X-Acosmi-Request-Id | Returned consumption identifier for original costs |
| Provider/task/operation ID | Specific 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.