PrismitaLEARN · PRACTICE · GROW

What are the common HTTP status codes an API should use?

Web API & REST HTTP Basic Fresher1–2 Yrs2–3 Yrs Conceptual 1 min read

Quick Answer

2xx: 200 OK, 201 Created (+ Location), 202 Accepted (async), 204 No Content (successful with no body). 4xx (client): 400 Bad Request, 401 Unauthenticated, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity (validation), 429 Too Many Requests. 5xx (server): 500 Internal Server Error, 503 Service Unavailable.

For success: 200 for a normal response, 201 for a POST that created something, with a Location header, and 204 for a successful operation that has no body, like a delete. For client errors: 400 for a malformed request, 401 if they're not authenticated, 403 if they are but they're not allowed, 404 for not found, 409 for a conflict like a duplicate, and 422 for a well-formed request that fails business validation, though a lot of APIs just use 400 for that too. And 500 for an unhandled server error.

  • 201 vs 200 — POST that creates a resource returns 201 with a Location header pointing at it.
  • 204 — successful DELETE or PUT with nothing to return.
  • 400 vs 422 — 400 for malformed requests (bad JSON, wrong type); 422 for well-formed but semantically invalid (business-rule validation). Many APIs just use 400 for both.
  • 401 vs 403 — 401 “you're not authenticated”, 403 “you are, but you're not allowed”.
  • 409 — a conflict like a duplicate or a concurrency clash.
All Web API & REST questions More on HTTP