Reading API error codes like 401, 404 and 429

The error number is a short message from the server about why your request failed. Read the number, read the message beside it, and you'll know where to look first.

How the numbers are grouped

The first digit gives the family.¹ MDN lists "Client error responses ( 400 – 499 )" and "Server error responses ( 500 – 599 )".

A client error means something about your request needs fixing. A server error means the trouble is at the service's end. That one sentence saves hours.

401: the key isn't accepted

¹ MDN says that although the standard word is "unauthorized", this response means "unauthenticated".¹ In its words, "the client must authenticate itself to get the requested response."

For an API, that usually points at the key.² Anthropic names a malformed, revoked or expired key.³ OpenAI adds a typo or an extra space in the key.

Copy the key again. Look for stray spaces. That's the first check. See what an API key is.

403: you're known, but not allowed

¹ MDN describes it as "The client does not have access rights to the content".² Anthropic says the key lacks permission for the resource you asked for.

First check: the key works, but this account or project may not be allowed to use that item. Ask whoever manages the account.

404: nothing at that address

¹ "The server cannot find the requested resource."² Anthropic's fix is to check the endpoint path and the resource IDs in the URL.

Spelling is the first check. Then check that the item you named exists. Addresses are explained in endpoints and methods.

429: too many requests

¹ MDN says the user "has sent too many requests in a given amount of time".³ OpenAI lists one cause as "You are using a loop or a script that makes frequent or concurrent requests."

First check: slow down and read the message. Some 429 replies mean a spending cap was reached, not a speed limit.³ OpenAI states "Retrying billing, spend, or quota errors won’t restore API access." So the message decides whether waiting helps. Limits and spending caps get their own guide: rate limits, quotas and charges.

500 and friends: the service's problem

¹ MDN calls a 500 generic: the server "cannot find a more appropriate 5XX status code to respond with."

Nothing in your request caused it, as a rule.² For its own server errors, Anthropic advises: "Retry the request with exponential backoff". That means waiting a little longer after each failed try. If it keeps happening, check the maker's status page and then contact them.

A calm order of checks

Start with the code and the message together. Many makers send a short text with the number. Then work through the cheap checks first: key, address, spelling.

If you ask a colleague or a support team for help, give them the code, the message and the time. Leave out keys, passwords, customer records and card numbers. Don't paste them into an AI tool either, unless your business's own policy allows it.

Two quick habits

• Write down the code before you change anything.
• Change one thing at a time, so you know what fixed it.

The code is the first line of every reply, as the guide on messages between apps shows.