Status codes

A status code is the server's three-digit summary of what happened to a request. Interviewers ask about the families, about close pairs (401 or 403, 500 or 503), and which code an API should return in a given situation, because your expected results in every API test depend on it. The meanings below follow RFC 9110, the HTTP standard; 429 comes from RFC 6585.

The five families

The first digit gives the family. 1xx codes are short "please wait" answers that you rarely see in tests. 2xx means the request was received, understood and accepted. 3xx means the client must do something more, such as follow a new URL or use its cache (the copy of an earlier answer that it saved). 4xx means the request was wrong, so sending it again unchanged usually will not help (429 Too Many Requests is the common exception: wait, then send it again). 5xx means the request may have been fine, but the server failed.

Success codes

• 200 OK: success, with a body that depends on the method (the data for GET, a result for POST).
• 201 Created: something new was created. The Location header usually points at it.
• 202 Accepted: accepted but not finished. The work may still fail, so a test must check the final state separately.
• 204 No Content: success with no body, common for DELETE and updates.

Redirects and caching

• 301 Moved Permanently and 302 Found: the resource is at the URL in Location. For historical reasons a client may turn a POST into a GET when following them.
• 307 and 308: the same idea, but the client must keep the method, so a POST stays a POST.
• 304 Not Modified: the answer to a conditional GET: a GET that says "send the data only if it changed". For example, the request has If-None-Match holding an ETag (a version tag the server gave earlier). If the client's saved copy is still current, the server answers 304 with no body.

Client errors

• 400 Bad Request: the server cannot process the request because of a client error, such as broken JSON.
• 401 Unauthorized: valid credentials are missing. Despite the name it is about authentication, and the server must send a WWW-Authenticate header.
• 403 Forbidden: the caller is known but not allowed. A server may answer 404 instead, to hide that the resource exists.
• 404 Not Found: nothing at that URL, or the server will not say.
• 405 Method Not Allowed: the resource does not support this method; the response must include an Allow header.
• 409 Conflict: the request clashes with the current state, such as a second user with an email that must be unique.
• 415 Unsupported Media Type: the body's format (its Content-Type) is not supported, for example plain text sent to an API that wants JSON.
• 422 Unprocessable Content: the JSON is correctly written but a value is invalid, such as a bad email. Many APIs use 400 instead; follow the documentation.
• 429 Too Many Requests: the client hit a rate limit (a cap on how many calls are allowed in a period of time), often with a Retry-After header saying how long to wait.

Server errors

500 Internal Server Error is an unexpected failure, usually a bug, and never an acceptable answer to bad input. 502 Bad Gateway and 504 Gateway Timeout come from a proxy or load balancer (a program that passes requests on to one or more real servers) that got a bad answer, or no answer in time, from the server behind it, so the useful logs are usually on that server. 503 Service Unavailable is a temporary state such as overload or maintenance, and may include Retry-After.

Choosing the expected code in a test

The API documentation is the contract, the written promise of what the API does. Where it is silent, a server usually checks the request in a fixed order, and the first check that fails decides the code:

Valid create                         -> 201 (+ Location)
Delete done, nothing to return       -> 204
Missing or expired token             -> 401
Valid token, not allowed             -> 403 (or 404 to hide the resource)
Duplicate unique email               -> 409 (or a documented 400/422)
Broken JSON                          -> 400
JSON sent as text/plain              -> 415
Too many calls                       -> 429
Unexpected crash                     -> 500, always a bug

A status code is evidence, not the verdict. A 201 does not prove the order was saved correctly, and a 403 does not prove nothing was deleted. Strong tests check the status, then the body, the key headers, and finally the stored data by reading it back.

How to answer in an interview

Name the five families first, then give the pairs with one example each: "401 means the server does not know who you are, 403 means it knows and says no; 500 is a bug, 503 is temporary." When asked "which code for X?", state the code, give the reason, and add "unless the documentation says otherwise".

Common mistakes

• Using 401 and 403 the wrong way round.
• Accepting a 500 as the "expected" answer to invalid input; it should be a 4xx.
• Passing a test on the status alone, without checking the body or the data.
• Ignoring APIs that return 200 with an error message in the body; clients, retries and monitoring all treat 2xx as success, so report it.

Recap

2xx is success, 3xx redirection, 4xx a client mistake, 5xx a server failure. Know the close pairs and the common codes by heart, take the expected code from the documentation, and treat the status as one piece of evidence. When a test suddenly gets 500, reproduce the request, compare it with the last passing run and read the server logs, searching for the request id (a unique ID the server often puts in a response header for each call).