2 min read
#api
#rest
#http
4. Status Codes
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.