API Error Explainer

How is each status code interpreted?

HTTP status codes are a small, fixed vocabulary, and almost every confusing API failure comes from one of a dozen of them. The explainer maps the code to what the server is claiming, then separates the two questions that matter: is this your fault or theirs, and is retrying safe.

The 4xx family means the request was rejected — wrong credentials, malformed body, missing permission, rate limit. Retrying an identical 4xx almost always fails identically, with 429 the exception. The 5xx family means the server broke while handling a request it accepted, so retrying with backoff is usually correct.

For each code the tool lists the causes that produce the overwhelming majority of real-world occurrences, in the order worth checking, along with the specific header or response field that normally confirms the diagnosis.

How do you use the API Error Explainer?

1. 1.Enter the status code and, if you have it, the response body — the body usually contains the real reason.
2. 2.Work through the listed causes in order rather than guessing.
3. 3.Check whether the code is retryable before adding retry logic; retrying a 400 forever is a common and expensive bug.
4. 4.For rate limits, read the Retry-After header instead of inventing a delay.

What can this tool not tell you?

• Many APIs use status codes loosely, returning 200 with an error body or 400 for authentication problems.
• It cannot see your request, so it cannot tell you which specific field is malformed.
• Provider-specific error codes carry more detail than the HTTP status and should be checked in their documentation.

What should you know about reading errors as a debugging shortcut, not a dead end?

An API error is the single cheapest debugging signal you get, because the server has already told you which category of problem occurred — you only need to translate it. Developers who skip straight to logging request payloads or adding retries lose that shortcut and end up rediscovering, by trial and error, information the status code already gave them for free. Treating the code as the first diagnostic step rather than an inconvenience to swallow turns a ten-minute investigation into a thirty-second one, especially under production pressure when a clear head is scarce.

Interpretation hinges on separating client fault from server fault before anything else, because the fix lives on opposite ends of the stack depending on which it is. A 4xx means your request needs to change — a header, a scope, a payload shape — and no amount of resilience engineering on the client will help. A 5xx means the fix is on the provider's side, and the correct client behaviour is patience with backoff, not investigation of your own request body, unless the same 5xx recurs on a request that previously succeeded.

What changes the answer most often is the response body, since providers frequently overload a single status code for several distinct failures — a 400 might mean bad JSON, an unknown field, or a value out of range, and only the body distinguishes them. The most common mistake is building retry logic before checking retryability, which turns a permanent authentication failure into an infinite loop that burns quota and hides the real problem from monitoring. Next, log the code and body together, and fix the loudest failing pattern first rather than every code in the reference table.

What do worked examples look like?

What do people ask most about this tool?

Which related tools should you try next?