The four status codes that matter when you wire an LLM API

I was debugging an agent that kept failing on a Tuesday afternoon. The error came back as a 402. My first instinct was to rotate the API key — that's what I'd done before when something looked auth-related. I generated a new key, updated the environment variable, restarted the agent, and got the exact same 402 back. The key wasn't the problem. The account was empty. I'd wasted time on the wrong fix.

That's the pattern I keep seeing with LLM API errors: four status codes account for most of what goes wrong, and the wrong reaction to each one costs real time. Here's what they actually mean, and why rotating the key is the wrong answer for three of the four.

401 — The Key Is Actually Bad

A 401 means the API couldn't authenticate you. Anthropic calls it authentication_error; OpenAI calls it Invalid Authentication. The key is missing, malformed, revoked, expired, or you're hitting the endpoint from a scope your organization doesn't allow.

But not every 401 is a dead key. Anthropic's docs note that a 401 whose message starts with CORS requests are not allowed for this Organization isn't a key problem at all — it's your browser trying to hit the API directly, and the organization's settings don't permit it. The fix there is to route the request through your backend, not to rotate the key.

The same applies to header format. If you're sending Authorization: Bearer to an endpoint that expects x-api-key: you'll get a 401 that has nothing to do with key validity. I've seen this catch people when they switch between providers without updating their client code.

So the reaction to a 401: check the header format first, check that you're in the right organization, clear any cached key, and only — only — generate a new key if all of those check out and the key is genuinely invalid.

402 — The Key Is Fine, Your Account Isn't

This is the one that wastes the most time, because the instinct is the same as for a 401. Swap the key. But a 402 isn't an auth problem. Anthropic calls it billing_error; Google calls it payment_required. The key works. The account can't pay.

The causes are all at the account level: depleted prepaid balance, expired payment method, unpaid invoice, or a spend limit you set yourself that you've hit. MDN describes 402 as a nonstandard code reserved for payment systems, and in the LLM context it means exactly what it says — your credentials are fine, but the account can't pay for the work.

The reaction is completely different. Check your payment details. Top up your balance. Renew your payment method. Look at your spend limits. Rotating the key doesn't change any of that, because the new key inherits the same account-level problem. I learned this the hard way on that Tuesday: I rotated keys a few times before I looked at the billing page.

403 — The Key Works, You Just Can't Use That Model

A 403 is the interesting one, because it means the API saw your key, accepted it, and then refused the specific thing you asked for. Anthropic calls it permission_error; OpenAI calls it PermissionDeniedError. The key is valid. You just don't have access to this resource.

The most common shape: you're trying to call a model your account tier doesn't include. On Anthropic, Claude Opus requires a higher usage tier than Claude Sonnet or Haiku. On OpenAI, newer or more capable models may be gated behind access requirements, and the docs also list unsupported countries or regions as a 403 cause. Meta's docs say the same thing — the key lacks permission for the requested model or feature, and the fix is in the Model API dashboard, not in your retry logic.

There's also the WAF angle. A 403 can come back from a web application firewall blocking your request pattern or your IP range, and that's not a key problem either. Google's docs note that a 403 can mean your project's API access is restricted, which is a project-level setting, not a key-level one.

The reaction: check which model you're calling and whether your account has access to it. Check if you're missing a required beta header. Check if your workspace admin restricted your key's model access. Don't rotate the key unless you've ruled all of that out — and even then, a new key from the same account will likely hit the same restrictions.

429 — Everything Works, You're Just Too Fast

A 429 means the key works, the account has money, and the model is accessible. You're being rate-limited. Anthropic calls it rate_limit_error; OpenAI distinguishes between rate_limit_error (you're sending requests too fast) and credit_balance_exhausted (which is actually a billing problem and would be a 402 in Anthropic's model). Meta's docs are explicit: 429 means you've exceeded your requests-per-minute or tokens-per-minute limit, and the fix is exponential backoff with jitter, not a new key.

The reaction here is to slow down. Check for a Retry-After header — if it's present, wait at least that long. If not, back off exponentially. Meta's docs recommend starting with a short delay and doubling it, capping retries. OpenAI's help center says the same: pace your requests, follow the Retry-After header, and don't retry billing or quota errors because they won't resolve until you address the underlying balance or limit.

The reason "issue a new key" is wrong here is that rate limits are tied to your organization or project, not to the key itself. A new key from the same organization hits the same limits. The key is working fine — the API is telling you you're asking too much of it too quickly.

---

The through-line is simple: 401 means the key is bad, 402 means the account is empty, 403 means the key can't reach that model, and 429 means you're too fast. Only the first one should ever trigger a key rotation. For the other three, rotating the key is like changing the lock on a door when the problem is the electricity, the access permit, or the crowd outside.