Choosing the Right HTTP Status Codes for REST APIs

Status Codes for CRUD Operations

Create (POST)

• 201 Created — Resource created successfully. Include Location header with new resource URL.
• 202 Accepted — Request accepted for async processing.
• 409 Conflict — Resource already exists or state conflict.

Read (GET)

• 200 OK — Resource found and returned.
• 404 Not Found — Resource doesn't exist.
• 304 Not Modified — Use cached version (conditional request).

Update (PUT/PATCH)

• 200 OK — Updated and returning the resource.
• 204 No Content — Updated, no body returned.
• 409 Conflict — Concurrent modification conflict.
• 422 Unprocessable Entity — Validation failed.

Delete (DELETE)

• 204 No Content — Deleted successfully.
• 202 Accepted — Deletion queued for processing.
• 404 Not Found — Resource already gone.

Error Codes to Know

• 400 Bad Request — Malformed request syntax, missing fields
• 401 Unauthorized — No valid credentials provided
• 403 Forbidden — Credentials valid but insufficient permissions
• 404 Not Found — Resource doesn't exist
• 422 Unprocessable Entity — Semantic errors (invalid email format)
• 429 Too Many Requests — Rate limit exceeded

Anti-Patterns

• Don't return 200 for errors — Use proper 4xx/5xx codes
• Don't use 500 for validation errors — That's a client error (4xx)
• Don't invent custom status codes — Use standard ones with error detail in the body