API Status Codes: When to Use Which

API Status Codes: When to Use Which

Status codes tell clients what happened. Using the right one is part of the API contract. Here is when to use each.

2xx: Success

• 200 OK: generic success. GET, PATCH.
• 201 Created: a new resource was created. POST.
• 204 No Content: success with no body. DELETE.

3xx: Redirection

• 301 Moved Permanently: the URL changed.
• 304 Not Modified: use cache.

4xx: Client Errors

• 400 Bad Request: malformed input (validation, missing fields).
• 401 Unauthorized: not authenticated (no token or invalid token).
• 403 Forbidden: authenticated but not allowed (wrong role).
• 404 Not Found: the resource does not exist.
• 405 Method Not Allowed: the path exists but the method is not supported.
• 409 Conflict: a conflict (duplicate email, version conflict).
• 410 Gone: the resource was removed permanently.
• 422 Unprocessable Entity: semantic errors (valid format but invalid value).
• 429 Too Many Requests: rate limited.

5xx: Server Errors

• 500 Internal Server Error: something broke on the server.
• 502 Bad Gateway: an upstream service returned an invalid response.
• 503 Service Unavailable: maintenance or downstream failure.
• 504 Gateway Timeout: an upstream service timed out.

Common Confusions

401 vs 403

401 means not authenticated (who are you?). 403 means not authorized (you cannot do that). Always check auth first, then authorization.

400 vs 422

400 means the request is malformed (bad JSON, missing required field). 422 means the request is well-formed but has semantic errors (email format is wrong, password too short). Many APIs use 400 for both; that is fine.

404 vs 401

If a resource exists but the user cannot see it, return 404 (not 403) to avoid leaking existence. For private resources, 404 is safer than 403.

Use the Code, Not Just the Body

Clients should be able to branch on the status code alone. Do not return 200 with an error body. Return the right code with the error body.

The Takeaway

Use 200 for GET/PATCH, 201 for POST, 204 for DELETE. Use 400 for validation, 401 for not authenticated, 403 for not authorized, 404 for not found, 409 for conflict, 422 for semantic errors, 429 for rate limited. Use 500 for server errors, 502/503/504 for gateway issues. Clients should be able to branch on the code alone.