api: YAML JSON TOON Database
version: 1.0.0
format: json
dataset:
  id: 43
  slug: http-status-code-best-practices
  title: HTTP Status Code Best Practices
  description: "Guidelines for proper HTTP status code usage in REST APIs: when to use each code, common mistakes, and industry conventions."
  summary: "Practical guidance on using HTTP status codes in APIs: precision, async semantics, redirects, rate limiting with 429, cache-aware codes, consistent error formats and idempotency, each with a recommendation and a common mistake."
  use_when:
    - You are writing or reviewing an API design guide.
    - You want a checklist of status-code mistakes to avoid.
  caveats:
    - These are conventions that most teams follow; some organizations adopt stricter or looser rules.
    - Match the codes to the semantics clients rely on, not to taste.
  related:
    - http-client-error-guide
    - http-server-error-guide
    - http-redirect-status-codes
    - http-methods-reference
  category: HTTP Status Codes
  category_slug: http-status-codes
  tags: http,status-codes,best-practices,rest,api-design,error-handling
  view_count: 0
  created_at: 1777673262
  updated_at: 1777673262
  entry_count: 8
  fields:
    - section: practices
      field: principle
      type: string
      example: Use precise status codes
    - section: practices
      field: recommendation
      type: string
      example: Choose the most specific code for each situatio…
    - section: practices
      field: common_mistake
      type: string
      example: Returning 400 for all client errors or 500 for …
    - section: practices
      field: example
      type: string
      example: POST /users with invalid email format -> 400 Ba…
data:
  practices:
    - principle: Use precise status codes
      recommendation: Choose the most specific code for each situation. 400 for bad syntax, 422 for semantic errors, 409 for conflicts.
      common_mistake: Returning 400 for all client errors or 500 for all server errors.
      example: POST /users with invalid email format -> 400 Bad Request. POST /users with duplicate email -> 409 Conflict.
    - principle: Never expose internal details in error responses
      recommendation: Return generic messages to clients; log detailed errors server-side. Use structured error bodies (RFC 7807 Problem Details).
      common_mistake: Returning stack traces or SQL errors in production responses.
      example: "{\"type\":\"https://api.example.com/errors/rate-limit\",\"title\":\"Too Many Requests\",\"status\":429,\"detail\":\"Please wait before retrying.\"}"
    - principle: Use 2xx correctly for async operations
      recommendation: 202 Accepted for async processing, 200 OK for immediate results, 201 Created for new resources.
      common_mistake: Always returning 200 for async endpoints even when resource not yet available.
      example: POST /jobs/submit -> 202 Accepted with Location header pointing to job status endpoint.
    - principle: Redirect semantics matter for SEO
      recommendation: 301 for permanent moves (search engines transfer ranking), 302 for temporary, 307/308 to preserve HTTP method.
      common_mistake: Using 302 for permanent URL changes, losing SEO link equity.
      example: Old URL permanently moved -> 301 Moved Permanently with Location header. Feature temporarily disabled -> 307 Temporary Redirect.
    - principle: "Rate limiting: use 429 with Retry-After"
      recommendation: Always include Retry-After header with 429 responses. Use informative error body with rate limit context.
      common_mistake: Returning 503 for rate limiting (reserved for server overload) or omitting Retry-After.
      example: "HTTP/1.1 429 Too Many Requests\nRetry-After: 120\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 0"
    - principle: Cache-aware status codes
      recommendation: Use 304 Not Modified with ETag/Last-Modified for conditional requests. Set Cache-Control and Expires headers on 200 responses.
      common_mistake: Returning full response body for unchanged resources or omitting cache validation headers.
      example: "GET /resource with If-None-Match: \"etag123\" -> 304 Not Modified (empty body, cached version still valid)."
    - principle: Consistent error response structure
      recommendation: Use a consistent JSON envelope for all errors across your API. Include error code, message, and optional details array.
      common_mistake: Inconsistent error formats between endpoints, making client error handling impossible.
      example: "{\"error\":{\"code\":\"VALIDATION_ERROR\",\"message\":\"Invalid input\",\"details\":[{\"field\":\"email\",\"reason\":\"already_taken\"}]}}"
    - principle: Idempotency and safe methods
      recommendation: GET, HEAD, OPTIONS, DELETE, PUT should be idempotent. POST and PATCH are not. Return 200 on successful DELETE even if resource existed.
      common_mistake: Returning 404 on idempotent DELETE (idempotent means same response for same request, 200 for first delete, 200 for subsequent).
      example: DELETE /users/123 (first time) -> 200 OK. DELETE /users/123 (again) -> 200 OK (idempotent, not 404).