REST API Status Codes and Error Response Design

HTTP/1.1 200 OK

# Standard success response with a body.

HTTP/1.1 201 Created
Location: /users/usr_123

# Successful resource creation.

HTTP/1.1 202 Accepted

# Accepted for asynchronous processing.

HTTP/1.1 204 No Content

# Success without a response body.

HTTP/1.1 304 Not Modified

# Cache validation succeeded; body omitted.

HTTP/1.1 400 Bad Request

# Malformed request syntax or invalid shape.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

# Missing or invalid authentication credentials.

HTTP/1.1 403 Forbidden

# Authenticated but not allowed to perform the action.

HTTP/1.1 404 Not Found

# The resource does not exist.

HTTP/1.1 409 Conflict

# Request conflicts with current resource state.

HTTP/1.1 412 Precondition Failed

# Optimistic concurrency guard failed.

HTTP/1.1 422 Unprocessable Content

# Well-formed request but semantic validation failed.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

# The client exceeded the rate limit.

HTTP/1.1 500 Internal Server Error

# Unexpected server-side failure.

{
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "An account with that email already exists.",
    "details": {
      "field": "email"
    },
    "request_id": "req_01HXYZ..."
  }
}

# A compact structured error response.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "One or more fields are invalid.",
    "fields": [
      { "name": "email", "code": "INVALID_FORMAT" },
      { "name": "password", "code": "TOO_SHORT" }
    ]
  }
}

# Return multiple field-level issues at once.