HTTP Status Codes

Status codes are part of your API design

Clients branch logic on status codes. Proxies and caches also rely on them. A clean status code strategy reduces client complexity and makes debugging faster.

Most-used success codes

• 200 OK: success with a response body
• 201 Created: a new resource was created (often include Location header)
• 204 No Content: success with no body (common for DELETE)

Common client error codes

• 400 Bad Request: invalid JSON, missing required fields, malformed parameters
• 401 Unauthorized: missing/invalid authentication
• 403 Forbidden: authenticated but not allowed
• 404 Not Found: resource doesn't exist (or you intentionally hide it)
• 409 Conflict: conflict with current state (duplicate, version conflict)
• 422 Unprocessable Entity: validation errors (well-formed but semantically wrong)
• 429 Too Many Requests: rate limit hit (include retry guidance)

Server error codes

• 500 Internal Server Error: unexpected failure
• 502/503: gateway/service availability issues

A consistent error body

Return machine-readable errors. Keep it stable. One proven shape is “problem details” style fields (title, status, detail, instance) plus optional errors map.

Example: validation error (422)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "errors": {
    "email": ["Email is required"],
    "age": ["Age must be 18 or older"]
  }
}

Common mistakes

• Using 200 for failures and putting “success=false” inside JSON
• Using 404 for everything (clients can't distinguish auth vs missing vs validation)
• Returning HTML error pages from API endpoints

Quick mapping

• Create success: 201
• Delete success: 204
• Invalid JSON: 400
• Missing auth: 401
• No permission: 403
• Not found: 404
• Duplicate / conflict: 409
• Validation: 422
• Rate limit: 429