HTTP Status Codes Explained for Developers and API Designers

Status codes are part of the API contract

HTTP status codes tell clients what happened at a protocol level. They do not replace a useful response body, but they give applications, proxies, browsers, monitoring tools, and developers a shared signal. Choosing the right code makes integrations easier to debug and failures easier to classify.

The broad groups matter first. 2xx means success, 3xx means redirection, 4xx means the client request has a problem, and 5xx means the server failed to handle a valid request. Within those groups, use the specific codes that communicate the situation without being overly clever.

Common choices

• 200 OK for successful reads and ordinary responses.
• 201 Created when a new resource was created.
• 400 Bad Request for malformed or invalid input.
• 401 Unauthorized for missing or invalid authentication, and 403 Forbidden for authenticated users without permission.
• 404 Not Found when the resource is not available to the caller.
• 409 Conflict for state conflicts such as duplicate creation or version mismatch.

Be consistent

APIs become frustrating when every endpoint invents its own error style. Pair status codes with structured error bodies that include a stable code, message, and useful details. Avoid returning 200 OK for errors because it forces every client to parse the body before knowing whether the call worked.

Good status code usage is not about memorizing every number. It is about making the result of a request obvious to humans and machines.