{
  "id": "api/rate-limit-exceeded-retry-after-malformed",
  "signature": "429 Too Many Requests: Retry-After header value is malformed or missing",
  "signature_zh": "429请求过多：Retry-After头值格式错误或缺失",
  "regex": "429\\s*Too\\s*Many\\s*Requests\\s*[:]?\\s*Retry\\-After\\s*(header|value)\\s*(malformed|missing|invalid)",
  "domain": "api",
  "category": "resource_error",
  "subcategory": null,
  "root_cause": "Server returns 429 with a Retry-After header that has an invalid format (e.g., non-numeric, negative, or missing entirely), causing clients to fail to implement proper backoff.",
  "root_cause_type": "generic",
  "root_cause_zh": "服务器返回429，但Retry-After头格式无效（例如非数字、负数或完全缺失），导致客户端无法实现正确的退避。",
  "versions": [
    {
      "version": "Nginx 1.24.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Cloudflare 2024",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS API Gateway 2024",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kong 3.5.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Hardcoding a fixed retry delay (e.g., 5 seconds) instead of parsing Retry-After",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Ignoring Retry-After and retrying immediately, causing repeated 429 responses",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Assuming Retry-After is always in seconds (when it could be an HTTP-date)",
      "fail_rate": 0.65,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Implement robust Retry-After parsing that handles both seconds and HTTP-date formats: `const retryAfter = response.headers.get('Retry-After'); let delay; if (retryAfter && /^\\d+$/.test(retryAfter)) { delay = parseInt(retryAfter) * 1000; } else if (retryAfter) { delay = new Date(retryAfter).getTime() - Date.now(); } else { delay = 5000; }`",
      "success_rate": 0.85,
      "how": "Implement robust Retry-After parsing that handles both seconds and HTTP-date formats: `const retryAfter = response.headers.get('Retry-After'); let delay; if (retryAfter && /^\\d+$/.test(retryAfter)) { delay = parseInt(retryAfter) * 1000; } else if (retryAfter) { delay = new Date(retryAfter).getTime() - Date.now(); } else { delay = 5000; }`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use exponential backoff with jitter as fallback when Retry-After is missing: `delay = Math.min(60000, Math.pow(2, attempt) * 1000 + Math.random() * 1000)`",
      "success_rate": 0.8,
      "how": "Use exponential backoff with jitter as fallback when Retry-After is missing: `delay = Math.min(60000, Math.pow(2, attempt) * 1000 + Math.random() * 1000)`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Contact API provider to fix Retry-After header format, and in the meantime, parse it leniently (e.g., extract first numeric value)",
      "success_rate": 0.7,
      "how": "Contact API provider to fix Retry-After header format, and in the meantime, parse it leniently (e.g., extract first numeric value)",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "实现健壮的Retry-After解析，处理秒数和HTTP日期格式：`const retryAfter = response.headers.get('Retry-After'); let delay; if (retryAfter && /^\\d+$/.test(retryAfter)) { delay = parseInt(retryAfter) * 1000; } else if (retryAfter) { delay = new Date(retryAfter).getTime() - Date.now(); } else { delay = 5000; }`",
    "当Retry-After缺失时，使用带抖动的指数退避作为回退：`delay = Math.min(60000, Math.pow(2, attempt) * 1000 + Math.random() * 1000)`",
    "联系API提供商修复Retry-After头格式，同时宽松解析（例如提取第一个数值）"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.8,
  "fix_success_rate": 0.7,
  "resolvable": "partial",
  "first_seen": "2024-08-01",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}