API Basics: What Are APIs and Why They MatterLesson 1.4

HTTP Status Codes Every API Developer Must Know

HTTP status codes, 2xx success, 3xx redirection, 4xx client errors, 5xx server errors, 200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500, 503

HTTP Status Codes Every API Developer Must Know

HTTP status codes are three-digit numbers returned by the server in every REST API response. They immediately communicate whether a request succeeded, failed, or requires further action. Using the correct status codes is a mark of a well-designed REST API — they allow clients to handle responses programmatically without parsing the response body.

DiagramHTTP Status Code Reference Chart

IMAGE PROMPT (replace this block with your generated image):

Flat reference card infographic on white background. Title: HTTP Status Codes Quick Reference. Four color-coded sections arranged in a 2x2 grid. Section 1 (2xx Success) — background: light green (#f0fdf4), border: #22c55e. List: 200 OK, 201 Created, 204 No Content with one-line descriptions. Section 2 (3xx Redirect) — background: light blue (#eff6ff), border: #3b82f6. List: 301 Moved Permanently, 304 Not Modified. Section 3 (4xx Client Error) — background: light yellow (#fffbeb), border: #f59e0b. List: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable, 429 Too Many Requests. Section 4 (5xx Server Error) — background: light red (#fef2f2), border: #ef4444. List: 500 Internal Server Error, 503 Service Unavailable. Each status code in bold monospace. Section headers use their respective border color. Brand accent color #3A5EFF used for the overall title and section title text. White background for the outer card.

2xx: Success

200 OK is the standard success response for GET, PUT, and PATCH requests. The requested operation completed successfully and the response body contains the result.

201 Created is returned after a successful POST that created a new resource. Always include the new resource in the body and a Location header.

204 No Content indicates success with no response body. Typically returned by DELETE and some PATCH operations where returning data is unnecessary.

3xx: Redirection

301 Moved Permanently tells the client that the resource has permanently moved to a new URL. 304 Not Modified is returned when a client uses conditional GET and the resource has not changed, allowing the client to use its cached version.

4xx: Client Errors

400 Bad Request means the request was malformed — invalid JSON, missing required fields, or incorrect data types. Always return a descriptive error message in the body.

401 Unauthorized means authentication is required but was not provided or is invalid. The client must authenticate before retrying.

403 Forbidden means the client is authenticated but does not have permission to access the resource. Unlike 401, sending credentials again will not help.

404 Not Found means the requested resource does not exist. This is one of the most common status codes in any API.

409 Conflict is returned when the request conflicts with the current state of the server — for example, attempting to create a user with an email address that already exists.

422 Unprocessable Entity is used when the request body is syntactically valid JSON but fails business logic validation.

429 Too Many Requests indicates the client has exceeded a rate limit. Include a Retry-After header to tell the client when it can try again.

5xx: Server Errors

500 Internal Server Error is the generic server-side error. It means something went wrong on the server that was not the client's fault. Never expose stack traces or internal error details to clients in production.

503 Service Unavailable means the server is temporarily unable to handle the request — due to overload or maintenance. Include a Retry-After header when possible.

Status Code Best Practices

Never return 200 OK with an error message in the body — this is a common antipattern called the false 200. Always use the most specific status code available. Document every status code your API can return so consumers know how to handle each case.