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 404 means the resource does not exist; a 403 means the client is not allowed to access it. Do not return 404 to 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.