Home › Docs › Errors and retries
How it worksErrors and retries
apicuts exposes OpenAI Responses (/v1/responses), OpenAI Chat Completions (/v1/chat/completions), and Anthropic Messages (/v1/messages), returning standard HTTP status codes and structured JSON error payloads your SDK already expects.
Status codes and gateway error codes
| Code | Error code / meaning | What to do |
|---|---|---|
| 400 | Bad request. Includes malformed JSON, role_system_not_supported on /v1/messages (use the top-level system field, not a role: "system" message), and model_endpoint_mismatch on /v1/messages (wrong model family for the endpoint). | Fix the request payload or route to the matching endpoint. Retrying unchanged won't help. |
| 401 | Unauthorized. Includes inference_key_required, inference_key_invalid, bearer_inference_key_required (/v1/responses requires Authorization: Bearer, not x-api-key), and conflicting_inference_credentials (sending both x-api-key and Authorization to /v1/messages). | Check $APICUTS_API_KEY (ack_...) in /app/keys and pass a single matching auth header. |
| 402 | Payment required (insufficient_wallet). Prepaid workspace balance cannot cover the estimated request reservation. | Add funds in /app/funding before retrying. |
| 403 | Forbidden. Your key isn't enabled for this model, endpoint, or workspace rule. | Check key scoping in /app/keys or email [email protected]. |
| 404 | Not found (model_not_found). The path or model ID is unknown or disabled for your key. | Check https://apicuts.ai/v1 vs https://apicuts.ai and query GET /v1/models for live model IDs. |
| 409 | Idempotency conflict. request_already_recorded means the same Idempotency-Key and payload already executed; idempotency_conflict means the same Idempotency-Key was reused with a different request body. | Generate a fresh unique Idempotency-Key per new request instead of replaying an old key. |
| 413 | Request too large (request_body_too_large). The request exceeds gateway payload or context limits. | Trim the prompt or context and split large inputs. |
| 422 | Validation error. Protocol or header rules failed: idempotency_key_required (/v1/chat/completions requires an Idempotency-Key matching [A-Za-z0-9._:-]{1,128}), unsupported_chat_request (/v1/chat/completions requires "stream": true), native_responses_streaming_required (/v1/responses requires "stream": true), unsupported_anthropic_version (/v1/messages requires anthropic-version: 2023-06-01), and model_endpoint_mismatch on /v1/responses. | Fix the missing header, streaming flag, version header, or endpoint before retrying. |
| 429 | Too many requests. Includes concurrency_limit (too many concurrent in-flight streams) and stream_disconnect_abuse (repeated mid-stream disconnects). | Retry with exponential backoff, lower concurrency, or review workspace activity in /app/overview. |
| 500 | Server error. Something failed inside the gateway. | Retry with backoff. |
| 502, 503, 504 | Upstream unavailable or timed out. Includes upstream_incomplete, supplier_disabled, customer_model_unavailable, supplier_capacity_unavailable, and supplier_receipt_unavailable. | Retry with backoff and inspect recent request status in /app/requests or enabled models via GET /v1/models. |
Upstream error handling
Upstream provider errors and stream interruptions surface as structured status codes without billing uncompleted reservations; automated cross-provider failover is tracked on the roadmap. See reliability and status.
Retries and idempotency keys
The OpenAI and Anthropic SDKs retry connection errors, 408, 429, and 5xx responses with exponential backoff (and note that the OpenAI SDK also retries 409 by default, so generate a fresh Idempotency-Key for each distinct /v1/chat/completions call rather than reusing keys across payloads):
import os, uuid
from openai import OpenAI
client = OpenAI(
base_url=os.environ.get("APICUTS_BASE_URL", "https://apicuts.ai/v1"),
api_key=os.environ["APICUTS_API_KEY"],
max_retries=3, # SDK default is 2
timeout=60.0, # seconds
)
# Pass a unique Idempotency-Key per logical /v1/chat/completions request
stream = client.chat.completions.create(
model=os.environ["APICUTS_MODEL_ID"], # Active model ID from GET /v1/models
messages=[{"role": "user", "content": "Hello"}],
stream=True,
extra_headers={"Idempotency-Key": str(uuid.uuid4())},
)Never retry 400, 401, 402, 403, 404, 413, or 422 errors unchanged, and never reuse an Idempotency-Key with a modified payload (409 idempotency_conflict).
Where to look
Every request appears in /app/requests and your savings dashboard (live demo) with its model, HTTP status, latency, token counts, and cost, while enabled models and tariffs appear via GET /v1/models. For support, email [email protected] or message your shared Telegram channel.
Want us to find your 20%+?
Get a free 360° cost report. Bring last month's provider usage and we'll show you your biggest waste and the first fix we'd ship.
Get a Free 360° Cost Report