How should an API client interpret common 4xx status codes?

Use the code to choose a diagnostic question, then compare that question with the request you actually sent and the API’s documentation. A 4xx status has a standardized general meaning, but an API may add its own behavior or error details; the code alone does not tell you exactly which field or condition caused the response. [S1]

Here’s a practical lookup:

1. 400 — Bad Request: The server perceives the request as a client error. Ask: “Did I send the request in the format and shape this endpoint expects?” [S1]
2. 401 — Unauthorized: In HTTP semantics, this means the request is unauthenticated. Ask: “Is the request being recognized as authenticated?” [S1]
3. 403 — Forbidden: The request lacks access rights. Ask: “Is this operation allowed for the identity and context the API recognizes?” [S1]
4. 404 — Not Found: The resource was not found. Ask: “Am I requesting the intended resource at the intended location?” An API may also use 404 rather than 403 to conceal that a resource exists. [S1]
5. 409 — Conflict: The request conflicts with the server’s current state. Ask: “Has something about the resource’s state changed or made this operation conflict?” [S1]
6. 422 — Unprocessable Content: The request is well-formed but cannot be followed because of semantic errors. Ask: “Are the supplied values meaningful and acceptable for this operation?” [S1]

These are starting points, not a diagnosis. The status code definitions do not establish what a particular API puts in its error body, or how that API handles each situation. [S1]

Start by separating the request’s presentation from its meaning. For a 400, inspect the request against the endpoint’s documented format and expected shape: “Did I send what this endpoint says it accepts?” For a 422, the general HTTP meaning points to a request that is well-formed but cannot be followed because of semantic errors: “Do these values make sense for this operation?” [S1]

For example, suppose you’re testing a hypothetical endpoint that accepts a booking request. If your request does not match the documented structure, that is a reason to investigate the request format. If it matches the structure but contains a value the operation cannot make sense of, investigate the value’s meaning. This is an illustrative distinction, not a claim about how any particular booking API classifies errors. Check the API’s documentation and any response details before deciding what to change.

Use the status as a prompt, not as proof of a specific configuration problem. With 401, ask whether the request is recognized as authenticated; with 403, ask whether the recognized request has access rights for the action. Those are the general HTTP meanings. [S1] You do not need to guess at an implementation or attempt to get around an access restriction; check the API’s authorized-use documentation or ask its administrator what access is intended.

For 404, first check that you are requesting the intended resource and location. Keep in mind that a server may return 404 instead of 403 to conceal a resource’s existence, so a 404 does not always settle whether the resource exists. [S1] The status definitions do not establish why a particular API chose that response.

Assume a hypothetical client sends a request and receives 409. Record the code, then ask whether the operation conflicts with the server’s current state; that is the general meaning of 409. [S1] Compare the request and the state you expected with the API’s documented behavior. Don’t assume which state changed or whether repeating the request will help: the code definition does not identify the application-specific cause. [S1]

A compact triage note you can copy is:

Status: [code] Request/operation: [brief description; omit secrets] First diagnostic question: [question suggested by the code] What I checked: [request details and relevant API documentation] Still unknown: [what the code does not establish]

For a 409, the first diagnostic question could be: “What about the current server state might conflict with this operation?” For a 422, it could be: “Are the request’s values meaningful and acceptable for this operation?” These questions guide investigation; they do not promise a particular error body or remedy. [S1]