REST API HTTP Status Codes
A reference guide to HTTP status codes for REST APIs, covering success responses, client errors, server errors, and when to use each code in practice.
HTTP status codes are the primary way your API communicates the outcome of a request. Use the standard codes consistently and resist the temptation to invent your own.
Success Codes (2xx)
| Code | Meaning | When to Use |
|---|---|---|
| 200 | OK | The request succeeded and the response body contains the requested data. |
| 201 | Created | A new resource was created. Include a Location header pointing to the new resource. |
| 204 | No Content | The request succeeded but there is no body to return — common for DELETE and some PUT responses. |
Client Error Codes (4xx)
| Code | Meaning | When to Use |
|---|---|---|
| 400 | Bad Request | The request is malformed or contains invalid syntax. |
| 401 | Unauthorised | The request lacks valid authentication credentials. |
| 403 | Forbidden | The credentials are valid, but the client does not have permission to perform the action. |
| 404 | Not Found | The requested resource does not exist. |
| 409 | Conflict | The request conflicts with the current state of the resource (e.g. a duplicate unique key). |
| 422 | Unprocessable Entity | The request is syntactically valid but fails semantic validation (e.g. business rule violations). |
| 429 | Too Many Requests | The client has exceeded the rate limit. |
Server Error Codes (5xx)
| Code | Meaning | When to Use |
|---|---|---|
| 500 | Internal Server Error | Something went wrong on the server. Log the full details internally; return only a generic message to the client. |
| 503 | Service Unavailable | The server is temporarily unable to handle requests (e.g. during maintenance or high load). |
Guidelines
- Be precise. A
404means the resource does not exist; a403means the client is not allowed to access it. Do not return404to hide the existence of a resource unless that is a deliberate security decision. - Stay consistent. Pick a small set of status codes and use them uniformly. Clients build logic around these codes; surprising them with unusual codes increases integration complexity.
- Never invent codes. Stick to the codes defined in the HTTP specification. Custom codes outside the standard ranges cause widespread compatibility issues.
Newsletter
A weekly newsletter on React, Next.js, AI-assisted development, and engineering. No spam, unsubscribe any time.