# 1. Repair decision **Decision: RATE-LIMIT CONTRACT DRIFT FOUND — repo patches and local tests can be prepared, but deployed behavior remains unverified.** Files disagree on the default quota: docs/OpenAPI say 120/min, middleware uses 100, and one route hard-codes 60. The 429 body, `Retry-After`, reset rules, exemptions, and client retry behavior also differ. I will repair repository consistency without choosing an unsupported business quota or accessing live infrastructure. # 2. Scope and boundary **Reviewed:** middleware, route configuration, OpenAPI, SDK retry helper, React client, mocks, tests, docs, and the supplied issue note. **Not accessed:** Redis, API gateway, CDN, production logs, traffic, customer keys, plan data, deployment variables, or live endpoints. This work aligns repository code, tests, schemas, and docs; it cannot prove deployed behavior. # 3. Contract source register | Source | Current statement | Status | |---|---|---| | `config/limits.ts` | default 100/min | Executable default | | `rateLimit.ts` | seconds-based `Retry-After` | Executable behavior | | `routes/reports.ts` | hard-coded 60/min | Unexplained override | | `openapi.yaml` | 120/min | Public contract candidate | | `docs/api-limits.md` | 120/min | Public contract candidate | | SDK helper | retries 429 immediately | Unsafe behavior | | React client | generic 429 error | Missing timing support | | Tests/mocks | two bodies; mixed header form | Conflicting contract | | Issue note | reported retry storms | Reported, not verified | # 4. Canonical repository contract No supplied source authoritatively chooses 100 or 120. The numeric default must remain **OWNER DECISION REQUIRED**. Safe canonical structure: - one typed default in `config/limits.ts`; - named route overrides instead of literals; - one shared 429 response schema; - `Retry-After` as non-negative integer seconds; - capped retries after the stated delay; - no mutation retry unless explicitly marked safe; - OpenAPI, docs, mocks, and tests sharing one contract. Proposed response: ```json { "error": { "code": "rate_limited", "message": "Request limit exceeded", "retry_after_seconds": 30 } } 5. Drift findings F1 — Default quota disagreement Risk: clients may expect 120 while code rejects at 100. Repair: centralize the value and add a consistency test. Blocked: final number needs API-owner approval. F2 — Unexplained reports override Risk: the endpoint throttles earlier without documented rationale. Repair: move 60 into a named reportsPerMinute policy and document its scope. Do not: remove it without evidence. F3 — Inconsistent 429 payload Risk: SDK and UI parse different shapes. Repair: create a shared response schema and update serializers, mocks, and assertions. F4 — Retry-After mismatch Runtime emits seconds while a mock emits an HTTP date. Repair: make seconds the repo default; keep a separate HTTP-date parser test only if deliberately supported. F5 — Immediate retry loop The SDK retries within the same window. Repair: parse the delay, wait, cap attempts, and use bounded jitter after the minimum delay. F6 — Unsafe mutation retry The generic wrapper can repeat POST requests. Repair: retry safe methods by default; require an explicit retry-safe flag for mutations. 6. Safe patch plan File Change config/limits.ts typed default plus named overrides rateLimit.ts shared 429 schema and seconds header routes/reports.ts replace magic number with named policy openapi.yaml document response, header, scope, approved quota SDK helper wait, cap attempts, guard mutations React client expose typed rate-limit state and delay tests/mocks align contract and add boundary cases docs explain identity, window, overrides, deployment unknowns 7. Deterministic test matrix Use a fake clock and local counter adapter: Request at quota succeeds; next returns 429. Retry-After is an integer and never negative. Advancing time resets the window as specified. Reports override is independent from the default. Exempt routes remain exempt only when configured. API keys do not share counters. SDK waits before retrying. SDK does not retry POST by default. Malformed headers use a bounded fallback. OpenAPI schema matches the runtime serializer. A consistency test detects duplicated quota literals. 8. Verification steps Run only local project commands: npm test -- rate-limit npm test -- sdk-retry npm run typecheck npm run lint npm run build Do not use real credentials or production services. 9. Production boundary Unknown: deployed quota and window algorithm; gateway versus application precedence; counter sharing across instances; customer-plan overrides; trusted proxy and identity rules; production reset timing. These need an operational check. 10. Human approval request Safe to approve now: shared schema, named override, deterministic tests, SDK wait handling, mutation guard, and documentation checks. Decisions required: 100 versus 120, whether reports remains 60, identity basis, window algorithm, exemptions, and gateway precedence. Status: PATCH READY FOR LOCAL REVIEW — NUMERIC QUOTA AND DEPLOYED ENFORCEMENT NOT VERIFIED Suggested commit: fix(rate-limit): align repo contract and retry handling