200 OK

What 200 means

200 is the default success response and means exactly what it says: the request was understood, authorised, and processed, and the body contains the result. For a GET that is the resource; for a POST or PUT it is the outcome of the operation.

The one thing worth being deliberate about is not using 200 for failures. A 200 carrying an error object in the body defeats every layer that reasons about status codes - HTTP caches, client retry logic, load balancer health checks, monitoring and alerting all key off the status line. Some RPC-over-HTTP protocols do this intentionally, but in a REST-style API it removes your most useful signal.

For a successful creation, prefer 201 with a Location header. For a successful operation with nothing to return, prefer 204. Both tell the client more than a bare 200 does.

Should a client retry?

Nothing to retry - the request succeeded.

FAQ

Should I return 200 with an error in the body?

Not in a REST-style API. Caches, retry logic, health checks and monitoring all read the status code, so a 200 with an error hides the failure from all of them. Use the status code as the machine-readable signal and the body for detail.

200 or 201 for a POST that creates something?

201 Created, with a Location header pointing at the new resource. 200 is acceptable when the POST performed an action rather than creating a resource.

Often confused with

• 201 Created The request succeeded and created a new resource.
• 204 No Content The request succeeded and there is deliberately no response body.