{"error": "Bad request"}

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/users",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "value": "not-an-email"
    }
  ]
}

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "Your API key does not have permission to delete orders. Required scope: orders:delete",
  "instance": "/orders/ord_abc123",
  "error_code": "INSUFFICIENT_PERMISSIONS",
  "required_scope": "orders:delete",
  "current_scopes": ["orders:read", "orders:write"]
}

{
  "type": "https://api.example.com/errors/{error-type}",
  "title": "Human-Readable Error Title",
  "status": 400,
  "detail": "Specific explanation of what went wrong for this particular request.",
  "instance": "/the/endpoint/that/failed",
  "error_code": "MACHINE_READABLE_CODE",
  "request_id": "req_abc123xyz",
  "timestamp": "2026-06-15T14:30:00Z"
}

{
  "type": "https://api.example.com/errors/malformed-request",
  "title": "Malformed Request",
  "status": 400,
  "detail": "Request body is not valid JSON. Unexpected token '}' at position 42.",
  "error_code": "MALFORMED_JSON"
}

{
  "type": "https://api.example.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "The Authorization header is missing or contains an invalid token.",
  "error_code": "AUTH_REQUIRED",
  "help_url": "https://api.example.com/docs/authentication"
}

WWW-Authenticate: Bearer realm="api.example.com", error="invalid_token"

{
  "type": "https://api.example.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Your API key does not have the 'orders:delete' scope.",
  "error_code": "FORBIDDEN",
  "required_scope": "orders:delete"
}

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No order found with ID 'ord_nonexistent'.",
  "error_code": "NOT_FOUND",
  "resource_type": "order",
  "resource_id": "ord_nonexistent"
}

{
  "type": "https://api.example.com/errors/conflict",
  "title": "Resource Conflict",
  "status": 409,
  "detail": "Order ord_abc123 is already shipped and cannot be cancelled.",
  "error_code": "INVALID_STATE_TRANSITION",
  "current_state": "shipped",
  "attempted_transition": "cancelled",
  "allowed_transitions": ["delivered", "returned"]
}

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "2 validation errors in request body.",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_FORMAT",
      "value": "not-an-email"
    },
    {
      "field": "quantity",
      "message": "Must be between 1 and 999",
      "code": "OUT_OF_RANGE",
      "value": 0,
      "constraints": {"min": 1, "max": 999}
    }
  ]
}

{
  "type": "https://api.example.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "error_code": "INTERNAL_ERROR",
  "request_id": "req_abc123xyz"
}

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "3 validation errors in request body.",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_FORMAT"
    },
    {
      "field": "shipping_address.zip_code",
      "message": "Must be a 5-digit US zip code",
      "code": "INVALID_FORMAT"
    },
    {
      "field": "items[0].quantity",
      "message": "Must be a positive integer",
      "code": "INVALID_TYPE"
    }
  ]
}

X-RateLimit-Limit: 1000           # Max requests per window
X-RateLimit-Remaining: 742        # Requests left in current window
X-RateLimit-Reset: 1718460000     # Unix timestamp when window resets

{
  "type": "https://api.example.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 1000 requests per hour. Try again in 258 seconds.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 258,
  "rate_limit": {
    "limit": 1000,
    "window": "1 hour",
    "reset_at": "2026-06-15T15:00:00Z"
  }
}

Retry-After: 258

{
  "type": "https://api.example.com/errors/service-unavailable",
  "title": "Service Temporarily Unavailable",
  "status": 503,
  "detail": "The order processing service is temporarily overloaded.",
  "error_code": "SERVICE_UNAVAILABLE",
  "retryable": true,
  "retry_after": 30,
  "retry_strategy": "exponential_backoff"
}

import time
import random

def retry_with_backoff(request_func, max_retries=3, base_delay=1.0):
    """Retry a request with exponential backoff and jitter."""
    for attempt in range(max_retries + 1):
        response = request_func()
        
        if response.status_code < 500 and response.status_code != 429:
            return response  # Non-retryable -- return immediately
        
        if attempt == max_retries:
            return response  # Final attempt -- return whatever we got
        
        # Calculate delay with exponential backoff + jitter
        delay = base_delay * (2 ** attempt)
        jitter = random.uniform(0, delay * 0.1)
        
        # Respect Retry-After header if present
        retry_after = response.headers.get("Retry-After")
        if retry_after:
            delay = max(delay, float(retry_after))
        
        time.sleep(delay + jitter)
    
    return response

# Response header
X-Request-Id: req_f47ac10b58cc4372

# Include in error responses
{
  "request_id": "req_f47ac10b58cc4372"
}

# Request
X-Correlation-Id: trace_from_client_abc

# Response (echo the client's ID + add your own)
X-Correlation-Id: trace_from_client_abc
X-Request-Id: req_f47ac10b58cc4372

// BAD: exposes stack trace, database info, file paths
{
  "error": "NullPointerException at OrderService.java:142",
  "sql": "SELECT * FROM orders WHERE id = 'ord_abc'; -- injected",
  "stack": ["at com.acmecorp.api.OrderService.getOrder(OrderService.java:142)", "..."]
}

// GOOD: generic message with request ID for internal lookup
{
  "type": "https://api.example.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred.",
  "request_id": "req_f47ac10b"
}

// BAD: different messages reveal which part is wrong
{"error": "User not found"}        // Reveals that the username is wrong
{"error": "Invalid password"}      // Reveals that the username is correct

// GOOD: same message for all auth failures
{"error": "Invalid credentials"}   // Doesn't reveal which part is wrong

ERROR_CATALOG = {
    "VALIDATION_ERROR": {
        "status": 422,
        "title": "Validation Error",
        "type_slug": "validation-error",
    },
    "NOT_FOUND": {
        "status": 404,
        "title": "Resource Not Found",
        "type_slug": "not-found",
    },
    "RATE_LIMIT_EXCEEDED": {
        "status": 429,
        "title": "Rate Limit Exceeded",
        "type_slug": "rate-limit-exceeded",
    },
    # ... more error codes
}

POST /orders
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "customer_id": "cust_42",
  "items": [{"product_id": "prod_101", "quantity": 2}]
}

HTTP/1.1 201 Created
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Idempotent-Replayed: false      # false on first call, true on replays

# On replay:
HTTP/1.1 201 Created
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Idempotent-Replayed: true       # Signals this is a cached replay

import uuid
from datetime import datetime, timedelta

# Server-side idempotency store (simplified)
IDEMPOTENCY_STORE: dict[str, dict] = {}
KEY_TTL = timedelta(hours=24)

def handle_idempotent_request(
    idempotency_key: str,
    request_hash: str,
    process_func,
) -> tuple[int, dict]:
    """Handle a request with idempotency.
    
    Args:
        idempotency_key: Client-provided UUID.
        request_hash: Hash of the request body (to detect reuse with different params).
        process_func: Callable that processes the request and returns (status, body).
    
    Returns:
        Tuple of (status_code, response_body).
    """
    if idempotency_key in IDEMPOTENCY_STORE:
        stored = IDEMPOTENCY_STORE[idempotency_key]
        
        # Check if the key was used with different request parameters
        if stored["request_hash"] != request_hash:
            return 422, {
                "error": "Idempotency key reused with different parameters"
            }
        
        # Check if the stored result has expired
        if datetime.utcnow() - stored["created_at"] > KEY_TTL:
            del IDEMPOTENCY_STORE[idempotency_key]
            # Fall through to process the request
        else:
            # Return the cached result
            stored["replayed"] = True
            return stored["status"], stored["body"]
    
    # Process the request
    status, body = process_func()
    
    # Store the result
    IDEMPOTENCY_STORE[idempotency_key] = {
        "status": status,
        "body": body,
        "request_hash": request_hash,
        "created_at": datetime.utcnow(),
        "replayed": False,
    }
    
    return status, body

# Server response with ETag
HTTP/1.1 200 OK
ETag: "a3f2b8c1d4e56789"
Content-Type: application/json

{"id": "ord_abc123", "status": "pending", "total": 5999}

# Client sends cached ETag
GET /orders/ord_abc123
If-None-Match: "a3f2b8c1d4e56789"

# If nothing changed: 304 Not Modified (no body -- saves bandwidth)
HTTP/1.1 304 Not Modified
ETag: "a3f2b8c1d4e56789"

# If something changed: 200 OK with new data and new ETag
HTTP/1.1 200 OK
ETag: "new_etag_value"
Content-Type: application/json

{"id": "ord_abc123", "status": "shipped", "total": 5999}

# Client A reads the order (gets ETag)
GET /orders/ord_abc123
→ ETag: "version_1"

# Client A updates the order (sends If-Match with the ETag)
PUT /orders/ord_abc123
If-Match: "version_1"
Content-Type: application/json

{"status": "shipped"}

# Scenario 1: No one else modified it → 200 OK
HTTP/1.1 200 OK
ETag: "version_2"

# Scenario 2: Client B modified it first → 412 Precondition Failed
HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/precondition-failed",
  "title": "Precondition Failed",
  "status": 412,
  "detail": "The resource has been modified since you last retrieved it. Fetch the latest version and retry.",
  "current_etag": "version_2_by_client_b"
}

import hashlib
import json

def generate_etag(data: dict | str) -> str:
    """Generate a strong ETag from data.
    
    Uses SHA-256 hash of the JSON-serialized data.
    """
    if isinstance(data, dict):
        content = json.dumps(data, sort_keys=True, separators=(",", ":"))
    else:
        content = str(data)
    
    hash_value = hashlib.sha256(content.encode("utf-8")).hexdigest()[:16]
    return f'"{hash_value}"'

# Product listing (cacheable by CDN for 10 minutes)
HTTP/1.1 200 OK
Cache-Control: public, max-age=300, s-maxage=600
ETag: "product_list_v42"
Vary: Accept, Accept-Encoding

# User's order history (only browser cache, revalidate always)
HTTP/1.1 200 OK
Cache-Control: private, no-cache
ETag: "user_orders_v15"

# Auth token response (never cache)
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache

# This response varies by Accept header and Authorization
Vary: Accept, Accept-Encoding, Authorization

Cache-Control: public, max-age=60, stale-while-revalidate=300

def update_order(order_id: str, updates: dict) -> dict:
    """Update an order and invalidate its cache."""
    order = database.update(order_id, updates)
    
    # Invalidate the specific order cache
    cache.delete(f"order:{order_id}")
    
    # Invalidate the order list cache (since the list content changed)
    cache.delete_pattern("order_list:*")
    
    return order

# Response for GET /orders/ord_abc123
Surrogate-Key: order-ord_abc123 customer-cust_42 orders

# When order changes, invalidate by surrogate key:
# PURGE all responses tagged with "order-ord_abc123"

# Server response
Cache-Control: no-cache
ETag: "v42"

# Client's next request
GET /orders/ord_abc123
If-None-Match: "v42"

# Server response (nothing changed)
HTTP/1.1 304 Not Modified
# No body transferred -- saves bandwidth

# Cacheable by CDN (different TTL for CDN vs. browser)
Cache-Control: public, max-age=60, s-maxage=3600
Surrogate-Control: max-age=3600      # Fastly/Varnish-specific
Vary: Accept, Accept-Encoding         # Important: tells CDN to cache variants