Errors and retries

apicuts uses the OpenAI API format, so errors reach your code the way your SDK already expects. Here's what each status code means and what to do about it.

Status codes

Code	Meaning	What to do
400	Bad request. The request is malformed, or the model doesn't support a parameter you sent.	Fix the request. Retrying it unchanged won't help.
401	Unauthorized. Your apicuts key is missing or wrong.	Check `APICUTS_API_KEY`.
403	Forbidden. Your key isn't allowed to use this model or route.	Check your routing rules, or ask in your shared channel.
404	Not found. The model name or the path doesn't exist.	Check the model name and your base URL.
413	Request too large. The request is over the model's context or size limit.	Trim the context or split the request.
429	Too many requests. You hit a rate limit or a usage limit.	Retry with backoff, or raise the limit.
500	Server error. Something failed inside the gateway or upstream.	Retry with backoff.
502, 503, 504	Upstream unavailable or timed out. Every eligible route failed or timed out. Failover tries healthy routes before you ever see this.	Retry with backoff.

Failover happens first

When a provider errors, slows down or goes offline, eligible requests move to a healthy route inside the gateway before an error reaches you. See reliability and status.

Retries

The official OpenAI SDKs already retry connection errors, 408, 409, 429 and 5xx responses with exponential backoff, twice by default. You can change that and set a timeout:

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["APICUTS_BASE_URL"],
    api_key=os.environ["APICUTS_API_KEY"],
    max_retries=3,   # the SDK default is 2
    timeout=60.0,    # seconds
)

Don't retry 400, 401, 403 or 404 errors. They won't succeed until the request or key changes.

Where to look

Every request appears in your savings dashboard with its model, provider, latency and cost. For anything else, ask in your shared Slack, WhatsApp or Telegram channel.

Want us to find your 20%?

Book a free 15-minute API cost teardown. Bring last month's provider usage and we'll show you your biggest waste and the first fix we'd ship.

Get a Free 15-Minute API Cost Teardown