From 2daa33be74d829138b3b92581843d4c61d3e72d2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 16:53:21 +0000 Subject: [PATCH] docs(protocol): name the 429 backoff member what the runtime actually emits `content/docs/protocol/kernel/error-handling.mdx` taught `details.retry_after` on three error envelopes and instructed clients to read `data.error.details.retry_after`. No producer emits that member: both 429 emitters build `details: { retryAfterSeconds, resetAt }` (`packages/runtime/src/endpoint-policy.ts`, `packages/runtime/src/security/inbound-rate-limit.ts`), and two tests pin the spelling. A client written from this page reads `undefined` on every real 429 and silently falls back to its own backoff against a service that just asked it to wait. Only `details`-bag members move. The `RetryStrategy` enum value `retry_after` is a different, correct use of the same token and is untouched in all seven of its sites (`content/docs/api/error-catalog.mdx` x4, `content/docs/references/api/errors.mdx` x3). Claude-Session: https://claude.ai/code/session_016N6xmWt5hYm94ffVEwGH8x Co-authored-by: Claude --- content/docs/protocol/kernel/error-handling.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/protocol/kernel/error-handling.mdx b/content/docs/protocol/kernel/error-handling.mdx index ff11cfd183..1bb2360754 100644 --- a/content/docs/protocol/kernel/error-handling.mdx +++ b/content/docs/protocol/kernel/error-handling.mdx @@ -420,7 +420,7 @@ never crosses HTTP. The refusal is emitted as the flat body shown above, and "details": { "limit": 1000, "window": "1m", - "retry_after": 45, + "retryAfterSeconds": 45, "quota_reset": "2024-01-16T14:31:00Z" } } @@ -528,7 +528,7 @@ async function fetchWithRetry(url, options = {}, maxRetries = 3) { "message": "Service temporarily unavailable", "details": { "reason": "database_maintenance", - "retry_after": 300, + "retryAfterSeconds": 300, "estimated_completion": "2024-01-16T15:00:00Z" } } @@ -652,7 +652,7 @@ Content-Type: application/json "details": { "limit": 1000, "window": "1m", - "retry_after": 45, + "retryAfterSeconds": 45, "quota_reset": "2024-01-16T14:31:00Z", "upgrade_url": "https://app.acme.com/billing/upgrade" }, @@ -736,7 +736,7 @@ async function fetchWithRetry(url, options = {}, maxRetries = 3) { if (!response.ok) { // Check if error is retryable if (data.error.code === 'RATE_LIMIT_EXCEEDED') { - const retryAfter = data.error.details.retry_after || 1; + const retryAfter = data.error.details.retryAfterSeconds || 1; await sleep(retryAfter * 1000); continue; } else if (data.error.code === 'INTERNAL_ERROR') {