悆悋惆惃ć‚ÆćƒŽćƒ¼ćƒˆ

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

Choose success codes per method; mind whether you return a body.

Common success codes

Method Typical success When to use
GET/HEAD 200 OK / 304 Not Modified Fetch. 304 for conditional GET matches (RFC 9110 13.1).
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 Full replace. 200 if returning a body; 204 if empty. 201 if the URI was new.
PATCH 200 OK / 204 No Content Partial update. 200 with a body, 204 without.
DELETE 200 OK / 204 No Content Idempotent deletes. Returning 204/200 even when already gone keeps retries simple.
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 Authenticated but not allowed.
404 Not Found Any No resource at URI. Some APIs still return 200/204 on repeated DELETEs.
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 If-Match/If-Unmodified-Since failed. Use for optimistic/pessimistic locking.
415 Unsupported Media Type POST/PUT/PATCH Unsupported Content-Type. Hint acceptable formats.
422 Unprocessable Content POST/PUT/PATCH Validation failed. Great for domain errors with JSON details (RFC 9110 15.5.21).
429 Too Many Requests Any Rate limit. Include Retry-After.
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.
  • Design DELETE as idempotent; returning 204/200 even when already deleted simplifies retries.
  • Avoid custom status codes; put business details in the body (e.g., application/problem+json).

Takeaway

Picking codes per RFC 9110 keeps clients, caches, and proxies predictable. 201/204/409/412 are your core tools for write operations.

< HTTP request methods in practice Conditional requests and ETag >