Choose the Correct HTTP Status Codes for CRUD APIs

1. Create (POST)

• 201 Created
  • A new resource was created successfully.
  • The newly-created items can be returned in the body of the response message, but must be locatable by the URL of the initiating request or by the URL in the value of the Location header provided with the response.
  • Example: POST /users → 201 Created, Location: /users/123.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/201
• 202 Accepted
  • The request was accepted but not finished yet (async job).
  • Use when work is queued (e.g., report generation, video processing).
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/202
• 400 Bad Request
  • Invalid JSON, missing fields, malformed request.
  • Ref : https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400
• 409 Conflict
  • Resource already exists or violates a uniqueness constraint.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/409
• 422 Unprocessable Entity
  • Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
  • Clients that receive a 422 response should expect that repeating the request without modification will fail with the same error.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/422

2. Read (GET)

• 200 OK
  • Resource or collection retrieved successfully.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200
• 206 Partial Content
  • For range requests (files, streams, pagination slices).
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/206
• 304 Not Modified
  • For conditional GETs (If-None-Match, If-Modified-Since).
  • Used with caching.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/304
• 400 Bad Request
  • Bad query parameters.
  • Ref : https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400
• 404 Not Found
  • Resource doesn’t exist.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404

3. Update (PUT/PATCH)

• 200 OK
  • Resource updated and returning its representation.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200
• 202 Accepted
  • Update queued for later (async job).
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/202
• 204 No Content
  • Resource updated successfully, nothing returned.
  • Common when the client already knows the resource state.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/204
• 400 Bad Request
  • Invalid payload.
  • Ref : https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400
• 404 Not Found
  • Target resource doesn’t exist.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404
• 409 Conflict
  • Update conflict (e.g., unique constraint, concurrent modification).
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/409
• 422 Unprocessable Entity
  • Validation errors on update.

4. Delete (DELETE)

• 200 OK
  • Resource deleted, returning confirmation JSON.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200
• 202 Accepted
  • Deletion scheduled asynchronously (background cleanup).
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/202
• 204 No Content
  • Resource deleted successfully. No body returned.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/204
• 404 Not Found
  • Resource doesn’t exist. Some APIs still return 204 for idempotency.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404

5. Extra Useful Codes

• 401 Unauthorized
  • Authentication required.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/401
• 403 Forbidden
  • Authenticated, but not authorized.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/403
• 429 Too Many Requests 
  • Rate limiting
  • A Retry-After header may be included to this response to indicate how long a client should wait before making the request again.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429
• 500 Internal Server Error 
  • Unexpected server error.
  • This error is a generic "catch-all" response to server issues, indicating that the server cannot find a more appropriate 5XX error to respond with.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/500
• 503 Service Unavailable
  • Common causes are that a server is down for maintenance or overloaded. 
  • During maintenance, server administrators may temporarily route all traffic to a 503 page.
  • Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/503