{
    "api": "YAML JSON TOON Database",
    "version": "1.0.0",
    "format": "json",
    "dataset": {
        "id": 2822,
        "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"
        ],
        "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\u2026"
            },
            {
                "section": "practices",
                "field": "common_mistake",
                "type": "string",
                "example": "Returning 400 for all client errors or 500 for \u2026"
            },
            {
                "section": "practices",
                "field": "example",
                "type": "string",
                "example": "POST \/users with invalid email format -> 400 Ba\u2026"
            }
        ],
        "category": "HTTP Status Codes",
        "category_slug": "http-status-codes",
        "tags": "http,status-codes,best-practices,rest,api-design,error-handling",
        "view_count": 28,
        "created_at": 1777673262,
        "updated_at": 1777673262
    },
    "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)."
            }
        ]
    }
}