From 464c3ac6004c9244c2b3f3364f98102f0fefeda7 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 16:13:18 +0000 Subject: [PATCH] docs(protocol): drop the unproduced rate-limit headers and the quota wire fence error-handling.mdx taught three wire artefacts that no producer emits. X-RateLimit-Limit / -Remaining / -Reset appeared in both 429 header blocks. Measured tree-wide over `git ls-files`, every literal occurrence of those three names is a READ of GitHub's own quota headers in scripts/pm tooling; no ObjectStack producer sets any of them on a response. Positive controls on the same probe: Retry-After 32 literal occurrences, X-Environment-Id 42. The signal that really is on the wire stays: Retry-After, plus the retryAfterSeconds / resetAt details already documented beside it. The QUOTA_EXCEEDED section carried a copyable five-member details bag. QUOTA_EXCEEDED has zero construction sites tree-wide; on the same probe nine declared catalog members light up (RATE_LIMIT_EXCEEDED 14, PERMISSION_DENIED 132, SERVICE_UNAVAILABLE 94) and the three retired members read zero. The section now states that the code is registered but unemitted, so a reader does not write a dead branch. Its heading and HTTP Status line are kept verbatim because check:error-status-conformance parses them; deleting them trips that gate's doc-removed branch against the unpinned baseline. The 503 Retry-After block is deliberately untouched: a 503 producer does set it (plugin-hono-server/src/current-user-endpoints.ts). Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH --- .../docs/protocol/kernel/error-handling.mdx | 35 +++++-------------- 1 file changed, 8 insertions(+), 27 deletions(-) diff --git a/content/docs/protocol/kernel/error-handling.mdx b/content/docs/protocol/kernel/error-handling.mdx index 530b221220..0d8a2ab17a 100644 --- a/content/docs/protocol/kernel/error-handling.mdx +++ b/content/docs/protocol/kernel/error-handling.mdx @@ -428,9 +428,6 @@ never crosses HTTP. The refusal is emitted as the flat body shown above, and **HTTP Headers:** ```http HTTP/1.1 429 Too Many Requests -X-RateLimit-Limit: 1000 -X-RateLimit-Remaining: 0 -X-RateLimit-Reset: 1705412460 Retry-After: 45 ``` @@ -462,28 +459,15 @@ async function fetchWithRetry(url, options = {}, maxRetries = 3) { **HTTP Status:** 429 **Meaning:** Monthly/daily quota exceeded -**Example:** -```json -{ - "success": false, - "error": { - "code": "QUOTA_EXCEEDED", - "message": "Monthly API quota exceeded", - "details": { - "quota": 10000, - "used": 10000, - "period": "monthly", - "reset": "2024-02-01T00:00:00Z", - "upgrade_url": "https://app.acme.com/billing/upgrade" - } - } -} -``` +**Not emitted today.** `QUOTA_EXCEEDED` is a registered member of the standard +error-code catalog (`StandardErrorCode`, `packages/spec/src/api/errors.zod.ts`), +but no ObjectStack producer emits it. No response carries this code, and none +carries a quota `details` bag — do not write a client branch against it. -**How to fix:** -- Wait for quota reset -- Upgrade to higher plan -- Optimize API usage +Quota enforcement that does exist answers with its own code rather than this one +(the SMS daily quota answers `TOO_MANY_REQUESTS`). For request pacing, the code +on the wire is `RATE_LIMIT_EXCEEDED` above, whose `Retry-After` header and +`retryAfterSeconds` / `resetAt` details are what a client acts on. ### Server Errors @@ -631,9 +615,6 @@ Authorization: Bearer **Response:** ```http HTTP/1.1 429 Too Many Requests -X-RateLimit-Limit: 1000 -X-RateLimit-Remaining: 0 -X-RateLimit-Reset: 1705412460 Retry-After: 45 Content-Type: application/json