HTTP methods × status codes
A quick table for “201 or 204?” moments. Pair methods with status codes following RFC 9110 semantics so clients behave predictably.
Success patterns
2xx indicates success. This table also includes 304, a 3xx revalidation response. HEAD responses, 204, and 304 have no content. 202 does not guarantee eventual completion.
Common success codes
| Method | Typical success | When to use |
|---|---|---|
| GET/HEAD | 200 OK / 304 Not Modified | Fetch; unchanged conditional GET/HEAD can return 304. HEAD has no body even with 200. A valid partial GET can return 206. |
| POST | 201 Created / 202 Accepted / 200 OK | Creation uses 201 + Location. Async queueing uses 202. Updates via POST may return 200. |
| PUT | 200 OK / 204 No Content / 201 Created | Successful modification of a current representation requires 200 or 204. Successful creation when no current representation exists requires 201 (RFC 9110 §9.3.4). |
| PATCH | 200 OK / 204 No Content | Successful updates can use 200 or 204. Patch formats and APIs that allow creation can also use 201 (RFC 5789). |
| DELETE | 200 OK / 204 No Content / 202 Accepted | 200 with a completion report, 204 without content, or 202 when accepted but not yet enacted. A later 404 can still be idempotent. |
| OPTIONS | 204 No Content | Capability response; common for CORS preflight. |
Frequent error codes
Use spec-aligned errors so clients can retry or render UX properly.
Picking errors
| Code | Typical methods | Meaning / hint |
|---|---|---|
| 400 Bad Request | Any | Malformed request. Include error details. |
| 401 Unauthorized | Any | Needs auth. Return WWW-Authenticate. |
| 403 Forbidden | Any | Request understood but refused. Insufficient privileges are one example; successful authentication is not a prerequisite. |
| 404 Not Found | Any | No current representation, or unwilling to disclose its existence. A repeated DELETE returning 404 does not violate idempotency. |
| 405 Method Not Allowed | Any | Method unsupported for this URI. Return Allow header (RFC 9110 15.5.6). |
| 409 Conflict | POST/PUT/PATCH/DELETE | State conflict (duplicate key, version clash). Explain resolution in body. |
| 412 Precondition Failed | PUT/PATCH/DELETE | A precondition specified in request headers failed. Not a general code for all locking failures. |
| 415 Unsupported Media Type | POST/PUT/PATCH | Unsupported request format or content coding. Hint acceptable formats. |
| 422 Unprocessable Content | POST/PUT/PATCH | The content type is understood and syntax is correct, but the instructions cannot be processed. Distinguish this from broken JSON syntax (RFC 9110 §15.5.21). |
| 429 Too Many Requests | Any | Rate limit (RFC 6585 §4). Retry-After is optional. The response must not be cached. |
| 500/503 | Any | Server error / temporarily unavailable. 503 pairs well with Retry-After. |
Design notes
A bit of alignment goes a long way for client behavior and caches.
Tips
- For POST creation, include Location header pointing to the new resource (RFC 9110 10.2.2).
- Use conditional requests (If-Match/If-None-Match) and return 412 or 304 appropriately; intermediaries will play nicer.
- Repeated DELETE responses can differ while preserving the same intended effect. Document how clients can check state after losing a response.
- Use appropriate standard codes and explain problems where a response body is allowed. application/problem+json (RFC 9457) is one option. Do not attach JSON error details to a 204 response.
Takeaway
Choose codes based on the actual result and preconditions, not just the method name. See safety and idempotency and conditional requests with 304 and 412.