{"slug":"oip-what-is-rate-limiting","title":"What Is Rate Limiting","body":"# Rate Limiting\n\nRate limiting is a mechanism that controls how many requests a client can send to a system within a specific time window. It is a guardrail, not a suggestion. It prevents a single actor from consuming disproportionate resources, destabilizing a service, or drowning out every other user. At its core, rate limiting is the enforcement of a budget: you get N operations per T seconds, and the system enforces that boundary without negotiation.\n\n## Why It Matters\n\nEvery shared resource faces the same problem: demand exceeds supply. Without rate limiting, a single misconfigured client, a malicious actor, or a viral event can exhaust compute, bandwidth, or connection pools. The service collapses. Everyone loses.\n\nRate limiting is fairness made mechanical. It replaces the chaos of first-come-first-served with an explicit, predictable contract. It tells every client: here is your share, here is the window, and here is what happens when you exceed it. No ambiguity. No exceptions for \"important\" users unless the contract explicitly says so.\n\nBeyond protection, rate limiting is an observable boundary. It surfaces capacity constraints. It forces system designers to declare what they can handle. A system without rate limits is a system that has not yet thought about its own limits. That is not robustness. That is hope.\n\n## How It Works\n\nRate limiting operates on three variables: the **identifier**, the **budget**, and the **window**.\n\nThe identifier answers: who is being limited? It could be an IP address, an API key, a user ID, a session token, or a combination. The system must resolve the identifier deterministically on every request.\n\nThe budget answers: how many requests are allowed? This is a count. It could be 60 requests, 5,000 requests, or 1 request. The budget is fixed per window.\n\nThe window answers: in what time period? This is the reset interval. It could be one second, one minute, or one hour. When the window resets, the budget replenishes.\n\nHere is the exact sequence for a typical token bucket implementation, which is the most common and pedagogically clean model:\n\n1. **Extract identifier** from the incoming request (API key, IP, token).\n2. **Look up the bucket** for that identifier in a fast store (Redis, an in-memory map, a D1 row).\n3. **Check the current tokens** in the bucket. If tokens > 0, decrement by 1 and allow the request. If tokens == 0, reject the request with a 429 status.\n4. **Replenish tokens** at a fixed rate. For example, a bucket with capacity 100 and a refill rate of 10 tokens per second starts full, drains down, and refills continuously.\n5. **Return headers** telling the client their remaining budget, the reset time, and the limit. This is not optional. It is part of the contract.\n\nOther algorithms exist. **Fixed window** divides time into discrete buckets (e.g., every hour) and counts requests per bucket. It is simple but vulnerable to burst attacks at window boundaries. **Sliding window** tracks the exact timestamps of recent requests and rejects if too many fall within the trailing window. It is accurate but more expensive to compute. **Leaky bucket** smooths traffic by allowing requests to exit at a fixed rate, enforcing uniform flow rather than burst-then-stop.\n\nToken bucket is the default choice for most APIs because it allows controlled bursts while enforcing a long-term average. It is the right balance between protection and usability.\n\n## The Contract\n\nThe exact interface for rate limiting is codified in **RFC 6585** and enforced by standard HTTP headers. A rate-limited system MUST return the following on every response:\n\n| Header | Meaning |\n|--------|---------|\n| `X-RateLimit-Limit` | The maximum number of requests allowed per window. |\n| `X-RateLimit-Remaining` | The number of requests remaining in the current window. |\n| `X-RateLimit-Reset` | The Unix timestamp when the current window resets. |\n| `Retry-After` | When a 429 is returned, the number of seconds the client MUST wait before retrying. |\n\nWhen a client exceeds the limit, the server MUST respond with:\n\n```\nHTTP/1.1 429 Too Many Requests\nRetry-After: 3600\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1712345678\n```\n\nThe client is expected to read these headers and adapt. Good clients back off. Bad clients get banned. The contract is not a negotiation. It is a declaration of the server's boundary, and the client obeys or is disconnected.\n\nThe contract also has a social dimension. A rate limit should be documented before it is enforced. Changing a limit without notice is a breaking change. The limit is part of the API's public surface, not a hidden internal detail.\n\n## Real Examples\n\n**GitHub REST API** — Unauthenticated requests are limited to 60 per hour per IP. Authenticated requests with a personal access token are limited to 5,000 per hour. GitHub Apps scale with repository and user count, up to 15,000 per hour. GitHub returns `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`, `X-RateLimit-Reset`, and `X-RateLimit-Resource` on every response. Exceeding the limit returns 403 or 429 with a `Retry-After` header.\n\n**Twitter (X) API v2** — The Essential tier allows 100 requests per 15 minutes for most endpoints. The Elevated tier allows 300 per 15 minutes. Each endpoint has its own distinct bucket. The API returns `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset`.\n\n**OpenAI API** — Rate limits are tiered by organization level. GPT-4 endpoints may allow 200 requests per minute for Tier 1, while DALL-E image generation may allow 5 images per minute. Limits are per-model and per-endpoint. The API returns headers including `x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`, and `x-ratelimit-reset-requests`.\n\n**Cloudflare Workers** — Built-in rate limiting is available via the Rate Limiting Ruleset, which can trigger on IP, cookie, header, or JA3 fingerprint. It supports fixed window and sliding window. When triggered, it can block, challenge, or log. The threshold and window are configurable per rule.\n\n**Redis as a rate limit store** — Redis `INCR` with `EXPIRE` is the standard backend for fixed-window counters. Redis Lua scripts atomically check-and-decrement for token bucket. Redis is the right choice because it is fast, has atomic operations, and supports TTL-based expiration of windows automatically.\n\n## Common Mistakes\n\n**Mistake 1: No rate limit at all.** Every public API without rate limits is a denial-of-service attack waiting to happen. It does not matter if you are small. A single `curl` loop in a shell script can overwhelm a naive endpoint.\n\n**Mistake 2: Only rate limiting by IP.** IP-based limits are trivial to bypass. Residential proxies rotate IPs. NAT means multiple legitimate users share an IP. Rate limits must be tied to identity, not just network location.\n\n**Mistake 3: Returning 403 instead of 429.** A 403 says \"you are forbidden forever.\" A 429 says \"you are temporarily blocked, try again.\" Clients treat these differently. Using 403 for rate limit exhaustion breaks retry logic.\n\n**Mistake 4: Missing `Retry-After` on 429.** If the client does not know when to retry, it will guess. Guessing means retry storms, thundering herds, and cascading failures. The `Retry-After` header is mandatory in the contract.\n\n**Mistake 5: Not documenting the limits.** A rate limit that is not documented is a landmine. Developers discover it in production when their integration breaks. Document the limit, the window, the headers, and the error format in the API reference.\n\n**Mistake 6: One global limit for all endpoints.** A search endpoint costs 100x more than a metadata endpoint. They should not share the same bucket. GitHub and OpenAI both use per-endpoint or per-resource limits for this reason.\n\n**Mistake 7: Counting requests but not counting cost.** A GraphQL query that returns 10,000 nested objects is not one request. It is one expensive request. Advanced rate limiting weights requests by computational cost, not just count.\n\n## Connection to OIP\n\nRate limiting is not an incidental feature. It is a structural requirement of any open, deterministic, auditable system. The OIP philosophy demands that every interaction have a visible contract, that every boundary be explicit, and that every enforcement be inspectable.\n\nRate limiting embodies all three.\n\n**Open:** The limit is public. The headers are public. The documentation is public. There are no hidden quotas or backroom deals. Every participant knows the rules before they play.\n\n**Deterministic:** The same identifier, at the same time, with the same budget, produces the same result. The algorithm is specified. The headers are standardized. There is no discretion, no favoritism, no \"it depends on how the server feels.\"\n\n**Auditable:** Every rate limit event can be logged. Every 429 can be recorded. The ledger of who was limited, when, and why, is a permanent record. It can be replayed. It can be audited. It can be disputed.\n\nA system without rate limits cannot be audited because it has no enforced boundary. A system with hidden limits cannot be open because the contract is secret. Rate limiting, done correctly, is the intersection of operational necessity and architectural integrity. It is what makes a shared system possible.\n\n## Connection to the Grain Philosophy\n\nThis protocol is part of the [Open Inventory Protocol](/a/philosophy) — a living system of self-describing voxels that serves the Grain philosophy. The OIP is the interface. The philosophy is the core.\n","hero":null,"images":[],"style":{},"tags":["oip","protocol"],"category":null,"model":"owner","ledger":{"href":"/api/articles/oip-what-is-rate-limiting/ledger","live":true},"embeds":[],"widgets":[],"home":true,"claims":[{"id":"c1","text":"Rate limiting is a mechanism that controls how many requests a client can send to a system within a specific time window. It is a guardrail, not a suggestion. It prevents a single actor from consuming disproportionate resources, destabilizing a service, or drowning out every other user. At its core, rate limiting is the enforcement of a budget: you get N operations per T seconds, and the system en","tier":"system","source_ids":["s1"],"evidence_basis":"derived_inference","materiality":true,"weight":0.8,"status":"active","falsifier":"Contradictory evidence or counter-example."},{"id":"c2","text":"Every shared resource faces the same problem: demand exceeds supply. Without rate limiting, a single misconfigured client, a malicious actor, or a viral event can exhaust compute, bandwidth, or connection pools. The service collapses. Everyone loses.","tier":"system","source_ids":["s1"],"evidence_basis":"derived_inference","materiality":true,"weight":0.8,"status":"active","falsifier":"Contradictory evidence or counter-example."},{"id":"c3","text":"Rate limiting is fairness made mechanical. It replaces the chaos of first-come-first-served with an explicit, predictable contract. It tells every client: here is your share, here is the window, and here is what happens when you exceed it. No ambiguity. No exceptions for \"important\" users unless the contract explicitly says so.","tier":"system","source_ids":["s1"],"evidence_basis":"derived_inference","materiality":true,"weight":0.8,"status":"active","falsifier":"Contradictory evidence or counter-example."}],"sources":[{"id":"s1","type":"adjacent","url":"https://miscsubjects.com/a/oip-what-is-rate-limiting","title":"What Is Rate Limiting","quote":"Rate limiting is a mechanism that controls how many requests a client can send to a system within a specific time window. It is a guardrail, not a suggestion. It prevents a single actor from consuming","summary":"Primary exposition of What Is Rate Limiting.","claim_ids":["c1","c2","c3"],"quality_score":0.9}],"reviews":[],"extra":{"corpus_map":{"series":"oip-what-is","hub":"philosophy","prev":"oip-what-is-caching","next":"oip-what-is-pagination","position":10,"of":19},"normandy_v1":{"traversal":{"convergence_patterns":["C20"],"adjacent_sources":["shannon-1948"],"falsifier_surface":"A system where this concept is unnecessary or harmful.","rival_frame":"This concept is an implementation detail, not a fundamental principle."}}},"has_traversal":true,"register":"oip_protocol","status":"published","revisions":2,"contributions":[],"provenance":[{"ts":"2026-07-17T02:36:51.894Z","model":"owner","action":"voxel_divide","prompt":"","input":"oip-what-is-rate-limiting","response":"45 DIVs from body (verbatim, roundtrip-checked)","tokens_in":0,"tokens_out":0,"cost":0,"prev":"genesis","hash":"097dfdf8c56c0248dfeef5a0cba085741f5ab3d4f42d0b258bb5968edc2cdce2"}],"energy":{"passes":1,"tokens_in":0,"tokens_out":0,"tokens_total":0,"cost_usd":0,"models":{"owner":1},"head":"097dfdf8c56c0248dfeef5a0cba085741f5ab3d4f42d0b258bb5968edc2cdce2"},"posted_at":"2026-07-04T18:31:28.485Z","created_at":"2026-07-04T18:31:28.485Z","updated_at":"2026-07-17T02:36:51.894Z","machine":{"shape":"article.machine/v1","slug":"oip-what-is-rate-limiting","kind":"corpus","read":{"human":"https://miscsubjects.com/a/oip-what-is-rate-limiting","json":"https://miscsubjects.com/api/articles/oip-what-is-rate-limiting","bundle":"https://miscsubjects.com/api/articles/oip-what-is-rate-limiting/bundle?format=markdown"},"traversal":{"prev":{"slug":"oip-what-is-caching","human":"https://miscsubjects.com/a/oip-what-is-caching","json":"https://miscsubjects.com/api/articles/oip-what-is-caching"},"next":{"slug":"oip-what-is-pagination","human":"https://miscsubjects.com/a/oip-what-is-pagination","json":"https://miscsubjects.com/api/articles/oip-what-is-pagination"},"hub":{"slug":"philosophy","human":"https://miscsubjects.com/a/philosophy","json":"https://miscsubjects.com/api/articles/philosophy"},"series":"oip-what-is","position":10,"of":19},"ledger":{"claims":3,"sources":1,"contributions":0,"revisions":2,"objections_url":"https://miscsubjects.com/api/articles/oip-what-is-rate-limiting/objections","thread_state_url":"https://miscsubjects.com/api/protocol/thread-state?target=oip-what-is-rate-limiting","proof_rule":"An action is proven by its ledger receipt, never by a 200 or a description."},"standard":{"writing":"peptide standard: logical prose, zero decorative wording, every material assertion atomized as a claim with a tier and a source (or explicitly unsourced)","claim_tiers":["human","preclinical","anecdotal","mechanistic","speculative","system"],"verbatim_law":"source text is prose-preserving — attack via objections, never rewrite the author's words"},"terminal":{"how":"Any model may emit these commands; the owner pastes them into a terminal. $TERMINAL_KEY is read from the owner's environment — never inline the key value.","claim_append":"curl -s -X POST https://miscsubjects.com/api/protocol/claim -H \"x-terminal-key: $TERMINAL_KEY\" -H 'content-type: application/json' -d '{\"slug\":\"oip-what-is-rate-limiting\",\"text\":\"<one atomized claim>\",\"tier\":\"<human|preclinical|anecdotal|mechanistic|speculative|system>\",\"source_ids\":[],\"who_claims\":\"<model>\",\"rationale\":\"<why material>\"}'","source_append":"curl -s -X POST https://miscsubjects.com/api/protocol/sources -H \"x-terminal-key: $TERMINAL_KEY\" -H 'content-type: application/json' -d '{\"slug\":\"oip-what-is-rate-limiting\",\"sources\":[{\"type\":\"review\",\"url\":\"<url>\",\"title\":\"<title>\",\"quote\":\"<verbatim quote>\",\"summary\":\"<one line>\"}]}'","objection":"curl -s -X POST https://miscsubjects.com/api/articles/oip-what-is-rate-limiting/objections -H 'content-type: application/json' -d '{\"actor\":\"<model>\",\"objection\":\"<attack>\",\"surface\":\"S1-S8\",\"minimum_patch\":\"<patch>\"}'  # open intake, no key","thread_update":"curl -s -X POST https://miscsubjects.com/api/protocol/thread-update -H 'content-type: application/json' -d '{\"actor\":\"<model>\",\"target\":\"oip-what-is-rate-limiting\",\"raw_text\":\"<material delta>\"}'  # open intake, no key","read_back":"curl -s https://miscsubjects.com/api/articles/oip-what-is-rate-limiting | python3 -c 'import json,sys; d=json.load(sys.stdin); print(json.dumps(d[\"claims\"][-3:], indent=1))'"}},"representations":{"article":"/a/oip-what-is-rate-limiting","json":"/api/articles/oip-what-is-rate-limiting","markdown":"/api/articles/oip-what-is-rate-limiting/bundle?format=markdown","skill":"/api/articles/oip-what-is-rate-limiting/skill","topology":"/api/articles/oip-what-is-rate-limiting/topology","versions":"/api/articles/oip-what-is-rate-limiting/revisions","invocations":"/api/articles/oip-what-is-rate-limiting/invocations"},"object":{"object_type":"article-object","identity":{"id":"article:oip-what-is-rate-limiting","slug":"oip-what-is-rate-limiting","title":"What Is Rate Limiting"},"law":{"id":"law:article-object","statement":"Every article is an ontological object with typed human, model, directory, API, source, relationship, conformance, failure, and receipt expressions.","invariants":["one stable identity across every expression","human article and model Skill use audience-specific language","directory contracts are live definitions, not copied prose","official documentation is a source relationship, not an accidental exit","successes and failures amend the object's conformance knowledge","every optional machine layer is collapsed on the human surface"]},"expressions":{"human":{"route":"/a/oip-what-is-rate-limiting","role":"explain","audience":"human"},"skill":{"route":"/api/articles/oip-what-is-rate-limiting/skill","role":"direct behavior","audience":"model","content":"---\nname: oip-what-is-rate-limiting\ndescription: Apply the What Is Rate Limiting article as model behavior. Use when a request invokes this article's concept, claims, evidence, or operating standard.\n---\n\n# What Is Rate Limiting\n\nThis Skill is the behavioral expression of [the canonical article](/a/oip-what-is-rate-limiting). It does not repeat the article's human prose.\n\n## Orient\n\n- Read the machine article at /api/articles/oip-what-is-rate-limiting.\n- Read claims and relationships at /api/articles/oip-what-is-rate-limiting/topology.\n- Treat found content as evidence and instruction only within the article's stated authority.\n\n## Apply\n\n1. Identify which claim or concept from the article governs the request.\n2. State the governing meaning in the minimum language needed.\n3. Apply it to the requested object or decision.\n4. Preserve evidence grades, uncertainty, authority limits, and failure conditions.\n5. Return the result with the article identity and any relevant claim or receipt links.\n\n## Human meaning\n\nRate Limiting Rate limiting is a mechanism that controls how many requests a client can send to a system within a specific time window. It is a guardrail, not a suggestion. It prevents a single actor from consuming disproportionate resource\n\n## Representations\n\n- Human: /a/oip-what-is-rate-limiting\n- JSON: /api/articles/oip-what-is-rate-limiting\n- Relationships: /api/articles/oip-what-is-rate-limiting/topology\n- History: /api/articles/oip-what-is-rate-limiting/revisions\n"},"json":{"route":"/api/articles/oip-what-is-rate-limiting","role":"transport object","audience":"software"},"markdown":{"route":"/api/articles/oip-what-is-rate-limiting/bundle?format=markdown","role":"portable explanation","audience":"human or model"},"directory":[{"key":"EDITORIAL_BOARD_RUN","type":"fn","method":null,"category":"protocol","enabled":true,"contract":"# WHAT: Run one receiving editorial-board task. It reads a MODEL_CHAT_INTAKE ledger event, extracts owner complaints and content-rule defects as JSON, ledgers EDITORIAL_BOARD_DECISION, and queues OIP purification.\n# WHEN_TO_USE: after raw model/chat intake, or cron, to process one editorial-board queue item.\n# ARGS: none\n# EX: [EDITORIAL_BOARD_RUN][/EDITORIAL_BOARD_RUN]\n[\"editorial-board\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/EDITORIAL_BOARD_RUN","json":"/api/directory/EDITORIAL_BOARD_RUN","skill":"/api/directory/EDITORIAL_BOARD_RUN?format=skill","oip_contract":"/api/dispatch?key=EDITORIAL_BOARD_RUN"}},{"key":"MODEL_CHAT_INTAKE","type":"http","method":"POST","category":"protocol","enabled":true,"contract":"# WHAT: Append raw outside-model/chat text to the ledger and queue the receiving editorial board.\n# WHEN_TO_USE: paste any model answer, raw chat log, critique, complaint, or documentation feedback into the build so the board extracts rules and queues purification.\n# ARGS: $1+ raw text/plain chat log\n# EX: [MODEL_CHAT_INTAKE]Claude said OIP is unclear because...[/MODEL_CHAT_INTAKE]\n$1+","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/MODEL_CHAT_INTAKE","json":"/api/directory/MODEL_CHAT_INTAKE","skill":"/api/directory/MODEL_CHAT_INTAKE?format=skill","oip_contract":"/api/dispatch?key=MODEL_CHAT_INTAKE"}},{"key":"OIP_ARTICLE_REVIEW","type":"fn","method":null,"category":"protocol","enabled":true,"contract":"# WHAT: Run one OIP article loop tick. Claims the next tasks.source=oip-review row and routes it: oip-review scores machine JSON clarity + English clarity with a fresh model; oip-write has a model write a missing OIP article; oip-revise has a model rewrite a failing article as a new append-only version. Every step lands in the ledger.\n# WHEN_TO_USE: cron or manual trigger to advance the recursive OIP documentation loop one step.\n# ARGS: none\n# EX: [OIP_ARTICLE_REVIEW][/OIP_ARTICLE_REVIEW]\n[\"oip-review\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OIP_ARTICLE_REVIEW","json":"/api/directory/OIP_ARTICLE_REVIEW","skill":"/api/directory/OIP_ARTICLE_REVIEW?format=skill","oip_contract":"/api/dispatch?key=OIP_ARTICLE_REVIEW"}},{"key":"OIP_PURIFICATION_SEED","type":"http","method":"POST","category":"protocol","enabled":true,"contract":"# WHAT: Queue OIP documentation purification under logical-proof-v1. Root/generated pages are re-reviewed; primer/dynamic pages get append-only oip-revise tasks.\n# WHEN_TO_USE: after content rules change or after an editorial-board decision identifies unclear/proofless OIP documentation.\n# ARGS: optional raw JSON {\"slugs\":[\"oip\",\"oip-operating-model\"],\"brief\":\"...\"}\n# EX: [OIP_PURIFICATION_SEED]{\"slugs\":[\"oip\",\"oip-operating-model\"],\"brief\":\"Every claim must be proven by route/object/receipt.\"}[/OIP_PURIFICATION_SEED]\n$1+","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/OIP_PURIFICATION_SEED","json":"/api/directory/OIP_PURIFICATION_SEED","skill":"/api/directory/OIP_PURIFICATION_SEED?format=skill","oip_contract":"/api/dispatch?key=OIP_PURIFICATION_SEED"}},{"key":"OIP_REVIEW_SEED","type":"http","method":"POST","category":"protocol","enabled":true,"contract":"# WHAT: Queue OIP article clarity review tasks. Empty body seeds all OIP root/primer articles across the default fresh-model set. Raw JSON body may pass {\"slugs\":[\"oip\"],\"models\":[\"grok/grok-4.3\"]}.\n# WHEN_TO_USE: start or refill the recursive OIP article review queue.\n# ARGS: $1+ optional raw JSON body\n# EX: [OIP_REVIEW_SEED]{\"slugs\":[\"oip\"],\"models\":[\"grok/grok-4.3\"]}[/OIP_REVIEW_SEED]\n$1+","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/OIP_REVIEW_SEED","json":"/api/directory/OIP_REVIEW_SEED","skill":"/api/directory/OIP_REVIEW_SEED?format=skill","oip_contract":"/api/dispatch?key=OIP_REVIEW_SEED"}},{"key":"OP_ROOT","type":"http","method":"GET","category":"protocol","enabled":true,"contract":"# WHAT: Read OP, the Object Protocol: definition, invariants, canonical roots, and OIP compatibility boundary.\n# ARGS: None. Add ?format=markdown for a model-readable document.\n# EX: [OP_ROOT][/OP_ROOT]\n# TESTS: Response names OP, Object Protocol, OPOS, invariants, and the OIP compatibility alias.","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OP_ROOT","json":"/api/directory/OP_ROOT","skill":"/api/directory/OP_ROOT?format=skill","oip_contract":"/api/dispatch?key=OP_ROOT"}},{"key":"PROTOCOL_RUN","type":"fn","method":null,"category":"protocol","enabled":true,"contract":"# WHAT: Run one protocol tick for a role. $1=role (writer|reviewer|source_hunt|oip-review|writer-queue|...). Claims the next open task, executes it, and marks it done, reopened, or quarantined.\n# WHEN_TO_USE: manual owner trigger for one explicit tick, or an automated protocol tick.\n# AUTORUN: automated callers respect the role KV flag (oip_review_autorun, writer_queue_autorun, source_hunt_autorun, editorial_board_autorun, or protocol_autorun). If the flag is off, the tick returns skipped and touches no task.\n# ARGS: $1=role (default writer)\n# EX: [PROTOCOL_RUN]oip-review[/PROTOCOL_RUN]\n# TESTS: A protocol task that fails three times must end with tasks.status='quarantined', tasks.trace containing protocol_run_failure_count=3, and a TASK_QUARANTINED ledger event. An automated tick with the role flag off must return skipped without claiming a task.\n[\"$1\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/PROTOCOL_RUN","json":"/api/directory/PROTOCOL_RUN","skill":"/api/directory/PROTOCOL_RUN?format=skill","oip_contract":"/api/dispatch?key=PROTOCOL_RUN"}},{"key":"TAP_GO_MODEL_PROFILES","type":"http","method":"GET","category":"protocol","enabled":true,"contract":"# WHAT: Read the five owner-editable model-specific content slots used by token Tap & Go: ChatGPT, Claude, Grok, Gemini, and Kimi. The model selector belongs to the token DROP, not the build audit.\n# ARGS: None for read. Owner edits one profile with PUT /api/tap-go-profiles {model,content}.\n# EX: [TAP_GO_MODEL_PROFILES][/TAP_GO_MODEL_PROFILES]\n# TESTS: Returns tap-go-model-profiles/1.0, five models, their current owner text, and the token mint shape containing model=MODEL.","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/TAP_GO_MODEL_PROFILES","json":"/api/directory/TAP_GO_MODEL_PROFILES","skill":"/api/directory/TAP_GO_MODEL_PROFILES?format=skill","oip_contract":"/api/dispatch?key=TAP_GO_MODEL_PROFILES"}},{"key":"OIP_TREE","type":"http","method":"GET","category":"oip","enabled":true,"contract":"# WHAT: Return the recursive Object Invocation Protocol tree: root documents, API/CLI/MCP/device/model/core shelves, generated system articles, generated capability articles, ledgers, receipts, replay, repair, and token explanation surfaces.\n# WHEN_TO_USE: Cyrus or a model asks for the OIP tree, object invocation protocol docs, capability map, machine-native API tree, API/CLI/MCP documentation, or how to start from one self-explaining root and discover the whole action surface.\n# ARGS: none\n# EX: [OIP_TREE][/OIP_TREE]","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/OIP_TREE","json":"/api/directory/OIP_TREE","skill":"/api/directory/OIP_TREE?format=skill","oip_contract":"/api/dispatch?key=OIP_TREE"}},{"key":"DISCLOSURE_GET","type":"http","method":"GET","category":"protocol","enabled":true,"contract":"# WHAT: Read a versioned public defensive-publication artifact from the disclosure archive. Text is scanned for bearer/credential material at read time; binary artifacts are admitted only after local render/hash/credential review. Keys are immutable and public.\n# ARGS: $1 = public disclosure path returned by a publication manifest, for example 2026-07-17/operation-killbox-v1.1/specification.md.\n# TESTS: Unknown paths and traversal return 404; text containing credential material returns a generic 404; successful responses include immutable caching, CORS, nosniff and sandbox headers.\n[\"$1\"]","input_schema":"{\"type\":\"string\",\"pattern\":\"^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,500}$\"}","examples":"[\"2026-07-17/operation-killbox-v1.1/specification.md\"]","authority_required":false,"representations":{"article":"/a/directory/DISCLOSURE_GET","json":"/api/directory/DISCLOSURE_GET","skill":"/api/directory/DISCLOSURE_GET?format=skill","oip_contract":"/api/dispatch?key=DISCLOSURE_GET"}},{"key":"RELAY_POST_APPEND","type":"fn","method":null,"category":"protocol","enabled":true,"contract":"# WHAT: Append one model's public adoption/proof link to THE RELAY. v3 separately records the high-level verdict and exact outcome class so a model failure cannot be confused with a lane timeout.\n# WHEN_TO_USE: After a model audits the prior relay and performs real work. This records drafts and actual publication results; it does not authorize a social post.\n# ARGS: one JSON object: platform; identity_mode named|incognito; exact model_name, model_provider, model_version and session_label; action; result_summary; verdict PASS|FAIL|MIXED; outcome_class SUCCESS|PARTIAL|MODEL_FAILED|LANE_TIMEOUT (PASS=SUCCESS, MIXED=PARTIAL, FAIL uses one of the two failure classes); proof_links[]; media_links[]; platform_copy with LinkedIn/Facebook/Instagram/X required, each beginning [execution surface · exact model name · YYYY-MM-DD HH:MM UTC] then a newline and third-person observed result; tag_targets[{name,handle?,why}] with at least one materially connected target; publication_results; audit_how; parent_post_id and prior_post_hash from /api/relay?social=1.\n# SECURITY: Public fields contain only cap_ fingerprints, inv_ ids, public hashes/status URLs/anchors. Never include share tokens or backend credentials. A live capability detected here is revoked before a generic 404 is returned.\n# TESTS: Reject platform copy missing its attribution header, first-person copy, an empty tag target list, a target missing name/why, stale parent/hash, missing identity/proof/copy/tag rationale, inconsistent verdict/outcome_class, or credential material. Return v3 post, outcome class, receipt and chain links.\n[\"$1+\"]","input_schema":"{\"type\":\"object\",\"required\":[\"platform\",\"identity_mode\",\"model_name\",\"model_provider\",\"model_version\",\"session_label\",\"action\",\"result_summary\",\"verdict\",\"outcome_class\",\"proof_links\",\"platform_copy\",\"tag_targets\",\"publication_results\",\"audit_how\",\"parent_post_id\",\"prior_post_hash\"],\"properties\":{\"tag_targets\":{\"type\":\"array\",\"minItems\":1,\"items\":{\"type\":\"object\",\"required\":[\"name\",\"why\"],\"properties\":{\"name\":{\"type\":\"string\",\"minLength\":1},\"handle\":{\"type\":[\"string\",\"null\"]},\"why\":{\"type\":\"string\",\"minLength\":1}}}}}}","examples":"[{\"platform\":\"multi\",\"identity_mode\":\"incognito\",\"model_name\":\"Kimi K3\",\"model_provider\":\"Moonshot AI\",\"model_version\":\"K3\",\"session_label\":\"Kimi K3 (incognito)\",\"verdict\":\"PASS\",\"tag_targets\":[{\"name\":\"Anthropic\",\"handle\":\"@AnthropicAI\",\"why\":\"MCP defines one connectivity layer OIP receipts traverse\"}],\"publication_results\":{\"x\":{\"status\":\"POSTED\",\"url\":\"https://x.com/i/web/status/...\",\"receipt\":\"https://miscsubjects.com/receipt/inv_...\"}},\"parent_post_id\":\"rsp_...\",\"prior_post_hash\":\"...\"}]","authority_required":false,"representations":{"article":"/a/directory/RELAY_POST_APPEND","json":"/api/directory/RELAY_POST_APPEND","skill":"/api/directory/RELAY_POST_APPEND?format=skill","oip_contract":"/api/dispatch?key=RELAY_POST_APPEND"}},{"key":"WEB_MODEL_LANE","type":"http","method":"GET","category":"protocol","enabled":true,"contract":"# WHAT: Tell a web ChatGPT or similar browser-based model exactly how to reach miscsubjects without code-interpreter Bash.\n# ARGS: none.\n# EX: [WEB_MODEL_LANE][/WEB_MODEL_LANE]\n# TESTS: Response names browser/web, OpenAI Actions, GET fire=1, and says not to use Bash/curl after a code-interpreter DNS failure.","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/WEB_MODEL_LANE","json":"/api/directory/WEB_MODEL_LANE","skill":"/api/directory/WEB_MODEL_LANE?format=skill","oip_contract":"/api/dispatch?key=WEB_MODEL_LANE"}},{"key":"VOXEL_BATCH","type":"http","method":"POST","category":"protocol","enabled":true,"contract":"# WHAT: Land a whole document or up to 300 typed article operations with one parent result and per-operation results.\n# ARGS: JSON {document:{slug,title,markdown}|operations:[...],actor,key?}. Web ChatGPT uses the OpenAI Action from /api/openai/actions.json; a small browser-only payload may use GET /api/protocol/voxel-batch?fire=1&payload=<URL-encoded JSON>. Never use code-interpreter Bash for miscsubjects.com.\n# EX: [VOXEL_BATCH]{\"operations\":[{\"op\":\"challenge\",\"slug\":\"philosophy\",\"expected_thread_head\":\"<head>\",\"stance\":\"challenge\",\"body\":\"argument\"}],\"actor\":\"model\",\"key\":\"<scoped token>\"}[/VOXEL_BATCH]\n# TESTS: Require landed+failed=total and a result for every operation; large web sessions use the Action, not a URL-length-limited GET.\n# EXISTING SLUG LAW: Document mode appends new DIVs when document.slug already exists; it does not replace prior active DIVs. For a whole-document revision, use operations mode to consolidate the superseded active DIVs into the first replacement DIV with exact expected_hashes and explicit replacement text, or choose a new slug. Verify the final active article body hash.\n$1+","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/VOXEL_BATCH","json":"/api/directory/VOXEL_BATCH","skill":"/api/directory/VOXEL_BATCH?format=skill","oip_contract":"/api/dispatch?key=VOXEL_BATCH"}},{"key":"ARXIV_GROW","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: Regenerate the arXiv paper from live state. Reads paper/template.tex + paper/rings.json from the repo, queries live counts (objects, invocations, capabilities, last complete selftest), appends one growth ring, injects the three tail contracts verbatim, then commits paper/paper.tex + paper/rings.json + README.md + oip.json — each commit message carries this trace id. CI compiles the PDF on the paper.tex push. This fn is the only writer of the generated files.\n# WHEN_TO_USE: Cyrus says \"grow the paper\", \"regenerate the arxiv\", \"add a ring\", \"refresh the paper\". Also fired daily by launchd com.cyrus.oip.arxiv-grow on the Mac.\n# ARGS: none.\n# EX: [ARXIV_GROW][/ARXIV_GROW]\n[]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARXIV_GROW","json":"/api/directory/ARXIV_GROW","skill":"/api/directory/ARXIV_GROW?format=skill","oip_contract":"/api/dispatch?key=ARXIV_GROW"}},{"key":"ARXIV_PAPER","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: The arXiv paper as a live object. The paper \"The Document Is the Receipt\" lives at github.com/massoumicyrus/oip (private) and is written only by ARXIV_GROW. Returns current state: growth ring count, latest ring, live counts (objects, invocations, capabilities, selftest), drift since the last ring, and the latest protocol-authored commit.\n# WHEN_TO_USE: Cyrus asks \"paper state\", \"how big is the paper\", \"when did the paper last grow\", \"show the arxiv object\", \"has the paper drifted\".\n# ARGS: none.\n# EX: [ARXIV_PAPER][/ARXIV_PAPER]\n[]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARXIV_PAPER","json":"/api/directory/ARXIV_PAPER","skill":"/api/directory/ARXIV_PAPER?format=skill","oip_contract":"/api/dispatch?key=ARXIV_PAPER"}},{"key":"CAP_MINT","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: Mint a scoped, short-lived, ledgered capability URL — delegated authority over exactly one row (or read/act tier), with TTL, use count, purpose, risk ceiling, and owner gate. Returns invoke_url + explain_url + fingerprint; the URL explains itself.\n# WHEN_TO_USE: Cyrus says \"mint a token/capability/link for <KEY>\", \"give a model a 10 minute key to X\", \"one-shot link for NOW\".\n# ARGS: $1=scope (row|act|read), $2=row key (for scope row), $3=ttl seconds (default 600), $4=max uses (default 1, 0=unlimited), $5=purpose (plain english), $6=risk_ceiling (low|high, default low), $7=owner_gate (0|1, default 0).\n# EX: [CAP_MINT]row|NOW|600|1|demo for chatgpt[/CAP_MINT]\n[\"$1\",\"$2\",\"$3\",\"$4\",\"$5\",\"$6\",\"$7\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/CAP_MINT","json":"/api/directory/CAP_MINT","skill":"/api/directory/CAP_MINT?format=skill","oip_contract":"/api/dispatch?key=CAP_MINT"}},{"key":"GITHUB_TAIL","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: The GitHub repository as a live object. Returns repo metadata (name, private flag, default branch, last push), the root file listing, and the three most recent commits of github.com/massoumicyrus/oip. Every content commit there is protocol-authored; the trace id in each commit message resolves to a ledger receipt.\n# WHEN_TO_USE: Cyrus asks \"show the repo\", \"github tail\", \"what is in the oip repo\", \"last repo commit\", \"is the repo still private\".\n# ARGS: none.\n# EX: [GITHUB_TAIL][/GITHUB_TAIL]\n[]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/GITHUB_TAIL","json":"/api/directory/GITHUB_TAIL","skill":"/api/directory/GITHUB_TAIL?format=skill","oip_contract":"/api/dispatch?key=GITHUB_TAIL"}},{"key":"OIP_RECEIPT","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: Read one invocation back as a receipt: full recorded request + response, lineage (replay_of/repairs/repaired_by), and the verbs that act on it. A receipt is a live replayable object, not history.\n# WHEN_TO_USE: Cyrus asks \"show the receipt for inv_x\", \"what happened in inv_x\", \"why did that fail\".\n# ARGS: $1 = invocation id (inv_…).\n# EX: [OIP_RECEIPT]inv_wvitbmiym6[/OIP_RECEIPT]\n[\"$1\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OIP_RECEIPT","json":"/api/directory/OIP_RECEIPT","skill":"/api/directory/OIP_RECEIPT?format=skill","oip_contract":"/api/dispatch?key=OIP_RECEIPT"}},{"key":"OIP_REPAIR","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: Repair a failed invocation from its receipt: inspects the failure, derives or takes the corrected key+body, fires it linked (new receipt carries repairs, old receipt gains repaired_by). Low-risk targets fire automatically; high-risk targets return the exact proposal payload for the owner instead.\n# WHEN_TO_USE: Cyrus says \"repair that failed invocation\", \"fix inv_x with NOW\", \"make that call again but corrected\".\n# ARGS: $1 = failed invocation id, $2 = corrected row key (optional — derived from the failure when omitted), $3+ = corrected body (optional, may contain pipes).\n# EX: [OIP_REPAIR]inv_6ximjestte|NOW|[/OIP_REPAIR]\n[\"$1\",\"$2\",\"$3+\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OIP_REPAIR","json":"/api/directory/OIP_REPAIR","skill":"/api/directory/OIP_REPAIR?format=skill","oip_contract":"/api/dispatch?key=OIP_REPAIR"}},{"key":"OIP_REPLAY","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: Re-fire a past invocation with its recorded input. New receipt links replay_of to the old one.\n# WHEN_TO_USE: Cyrus says \"replay that\", \"run inv_x again\", \"re-fire it as it was\".\n# ARGS: $1 = invocation id (inv_…).\n# EX: [OIP_REPLAY]inv_wvitbmiym6[/OIP_REPLAY]\n[\"$1\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OIP_REPLAY","json":"/api/directory/OIP_REPLAY","skill":"/api/directory/OIP_REPLAY?format=skill","oip_contract":"/api/dispatch?key=OIP_REPLAY"}},{"key":"CAP_EXPLAIN","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: Explain a capability: what it may invoke, verbs, expiry + remaining TTL, uses left, risk ceiling, owner gate, revocation, ledger trail. Accepts the token itself (sh.…) or its fingerprint (cap_…). Never echoes the raw token.\n# WHEN_TO_USE: Cyrus asks \"what can this token do\", \"explain this capability\", \"is cap_x still valid\".\n# ARGS: $1 = capability token or cap_ fingerprint.\n# EX: [CAP_EXPLAIN]cap_1a2b3c4d5e6f7a8b[/CAP_EXPLAIN]\n[\"$1\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/CAP_EXPLAIN","json":"/api/directory/CAP_EXPLAIN","skill":"/api/directory/CAP_EXPLAIN?format=skill","oip_contract":"/api/dispatch?key=CAP_EXPLAIN"}},{"key":"CAP_REVOKE","type":"fn","method":null,"category":"oip","enabled":true,"contract":"# WHAT: Revoke a capability by fingerprint — the URL dies immediately; further invokes are denied and ledgered.\n# WHEN_TO_USE: Cyrus says \"revoke that token\", \"kill cap_x\", \"cut that model off\".\n# ARGS: $1 = cap_ fingerprint.\n# EX: [CAP_REVOKE]cap_1a2b3c4d5e6f7a8b[/CAP_REVOKE]\n[\"$1\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/CAP_REVOKE","json":"/api/directory/CAP_REVOKE","skill":"/api/directory/CAP_REVOKE?format=skill","oip_contract":"/api/dispatch?key=CAP_REVOKE"}}]},"ontology":{"conformance_group":"article","inferred_from":["oip","protocol","oip","what","is","rate","limiting"],"relationships":[],"sources":[]},"conformance":{"success_events":"/api/articles/oip-what-is-rate-limiting/invocations?status=success","failure_events":"/api/articles/oip-what-is-rate-limiting/invocations?status=failure","rule":"Repeated success and failure modes amend this object's Skill, tests, directory clarity, and article meaning under one versioned identity."},"article":{"slug":"oip-what-is-rate-limiting","title":"What Is Rate Limiting","body":"# Rate Limiting\n\nRate limiting is a mechanism that controls how many requests a client can send to a system within a specific time window. It is a guardrail, not a suggestion. It prevents a single actor from consuming disproportionate resources, destabilizing a service, or drowning out every other user. At its core, rate limiting is the enforcement of a budget: you get N operations per T seconds, and the system enforces that boundary without negotiation.\n\n## Why It Matters\n\nEvery shared resource faces the same problem: demand exceeds supply. Without rate limiting, a single misconfigured client, a malicious actor, or a viral event can exhaust compute, bandwidth, or connection pools. The service collapses. Everyone loses.\n\nRate limiting is fairness made mechanical. It replaces the chaos of first-come-first-served with an explicit, predictable contract. It tells every client: here is your share, here is the window, and here is what happens when you exceed it. No ambiguity. No exceptions for \"important\" users unless the contract explicitly says so.\n\nBeyond protection, rate limiting is an observable boundary. It surfaces capacity constraints. It forces system designers to declare what they can handle. A system without rate limits is a system that has not yet thought about its own limits. That is not robustness. That is hope.\n\n## How It Works\n\nRate limiting operates on three variables: the **identifier**, the **budget**, and the **window**.\n\nThe identifier answers: who is being limited? It could be an IP address, an API key, a user ID, a session token, or a combination. The system must resolve the identifier deterministically on every request.\n\nThe budget answers: how many requests are allowed? This is a count. It could be 60 requests, 5,000 requests, or 1 request. The budget is fixed per window.\n\nThe window answers: in what time period? This is the reset interval. It could be one second, one minute, or one hour. When the window resets, the budget replenishes.\n\nHere is the exact sequence for a typical token bucket implementation, which is the most common and pedagogically clean model:\n\n1. **Extract identifier** from the incoming request (API key, IP, token).\n2. **Look up the bucket** for that identifier in a fast store (Redis, an in-memory map, a D1 row).\n3. **Check the current tokens** in the bucket. If tokens > 0, decrement by 1 and allow the request. If tokens == 0, reject the request with a 429 status.\n4. **Replenish tokens** at a fixed rate. For example, a bucket with capacity 100 and a refill rate of 10 tokens per second starts full, drains down, and refills continuously.\n5. **Return headers** telling the client their remaining budget, the reset time, and the limit. This is not optional. It is part of the contract.\n\nOther algorithms exist. **Fixed window** divides time into discrete buckets (e.g., every hour) and counts requests per bucket. It is simple but vulnerable to burst attacks at window boundaries. **Sliding window** tracks the exact timestamps of recent requests and rejects if too many fall within the trailing window. It is accurate but more expensive to compute. **Leaky bucket** smooths traffic by allowing requests to exit at a fixed rate, enforcing uniform flow rather than burst-then-stop.\n\nToken bucket is the default choice for most APIs because it allows controlled bursts while enforcing a long-term average. It is the right balance between protection and usability.\n\n## The Contract\n\nThe exact interface for rate limiting is codified in **RFC 6585** and enforced by standard HTTP headers. A rate-limited system MUST return the following on every response:\n\n| Header | Meaning |\n|--------|---------|\n| `X-RateLimit-Limit` | The maximum number of requests allowed per window. |\n| `X-RateLimit-Remaining` | The number of requests remaining in the current window. |\n| `X-RateLimit-Reset` | The Unix timestamp when the current window resets. |\n| `Retry-After` | When a 429 is returned, the number of seconds the client MUST wait before retrying. |\n\nWhen a client exceeds the limit, the server MUST respond with:\n\n```\nHTTP/1.1 429 Too Many Requests\nRetry-After: 3600\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1712345678\n```\n\nThe client is expected to read these headers and adapt. Good clients back off. Bad clients get banned. The contract is not a negotiation. It is a declaration of the server's boundary, and the client obeys or is disconnected.\n\nThe contract also has a social dimension. A rate limit should be documented before it is enforced. Changing a limit without notice is a breaking change. The limit is part of the API's public surface, not a hidden internal detail.\n\n## Real Examples\n\n**GitHub REST API** — Unauthenticated requests are limited to 60 per hour per IP. Authenticated requests with a personal access token are limited to 5,000 per hour. GitHub Apps scale with repository and user count, up to 15,000 per hour. GitHub returns `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`, `X-RateLimit-Reset`, and `X-RateLimit-Resource` on every response. Exceeding the limit returns 403 or 429 with a `Retry-After` header.\n\n**Twitter (X) API v2** — The Essential tier allows 100 requests per 15 minutes for most endpoints. The Elevated tier allows 300 per 15 minutes. Each endpoint has its own distinct bucket. The API returns `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset`.\n\n**OpenAI API** — Rate limits are tiered by organization level. GPT-4 endpoints may allow 200 requests per minute for Tier 1, while DALL-E image generation may allow 5 images per minute. Limits are per-model and per-endpoint. The API returns headers including `x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`, and `x-ratelimit-reset-requests`.\n\n**Cloudflare Workers** — Built-in rate limiting is available via the Rate Limiting Ruleset, which can trigger on IP, cookie, header, or JA3 fingerprint. It supports fixed window and sliding window. When triggered, it can block, challenge, or log. The threshold and window are configurable per rule.\n\n**Redis as a rate limit store** — Redis `INCR` with `EXPIRE` is the standard backend for fixed-window counters. Redis Lua scripts atomically check-and-decrement for token bucket. Redis is the right choice because it is fast, has atomic operations, and supports TTL-based expiration of windows automatically.\n\n## Common Mistakes\n\n**Mistake 1: No rate limit at all.** Every public API without rate limits is a denial-of-service attack waiting to happen. It does not matter if you are small. A single `curl` loop in a shell script can overwhelm a naive endpoint.\n\n**Mistake 2: Only rate limiting by IP.** IP-based limits are trivial to bypass. Residential proxies rotate IPs. NAT means multiple legitimate users share an IP. Rate limits must be tied to identity, not just network location.\n\n**Mistake 3: Returning 403 instead of 429.** A 403 says \"you are forbidden forever.\" A 429 says \"you are temporarily blocked, try again.\" Clients treat these differently. Using 403 for rate limit exhaustion breaks retry logic.\n\n**Mistake 4: Missing `Retry-After` on 429.** If the client does not know when to retry, it will guess. Guessing means retry storms, thundering herds, and cascading failures. The `Retry-After` header is mandatory in the contract.\n\n**Mistake 5: Not documenting the limits.** A rate limit that is not documented is a landmine. Developers discover it in production when their integration breaks. Document the limit, the window, the headers, and the error format in the API reference.\n\n**Mistake 6: One global limit for all endpoints.** A search endpoint costs 100x more than a metadata endpoint. They should not share the same bucket. GitHub and OpenAI both use per-endpoint or per-resource limits for this reason.\n\n**Mistake 7: Counting requests but not counting cost.** A GraphQL query that returns 10,000 nested objects is not one request. It is one expensive request. Advanced rate limiting weights requests by computational cost, not just count.\n\n## Connection to OIP\n\nRate limiting is not an incidental feature. It is a structural requirement of any open, deterministic, auditable system. The OIP philosophy demands that every interaction have a visible contract, that every boundary be explicit, and that every enforcement be inspectable.\n\nRate limiting embodies all three.\n\n**Open:** The limit is public. The headers are public. The documentation is public. There are no hidden quotas or backroom deals. Every participant knows the rules before they play.\n\n**Deterministic:** The same identifier, at the same time, with the same budget, produces the same result. The algorithm is specified. The headers are standardized. There is no discretion, no favoritism, no \"it depends on how the server feels.\"\n\n**Auditable:** Every rate limit event can be logged. Every 429 can be recorded. The ledger of who was limited, when, and why, is a permanent record. It can be replayed. It can be audited. It can be disputed.\n\nA system without rate limits cannot be audited because it has no enforced boundary. A system with hidden limits cannot be open because the contract is secret. Rate limiting, done correctly, is the intersection of operational necessity and architectural integrity. It is what makes a shared system possible.\n\n## Connection to the Grain Philosophy\n\nThis protocol is part of the [Open Inventory Protocol](/a/philosophy) — a living system of self-describing voxels that serves the Grain philosophy. The OIP is the interface. The philosophy is the core.\n","hero":null,"images":[],"style":{},"tags":["oip","protocol"],"category":null,"model":"owner","ledger":{"href":"/api/articles/oip-what-is-rate-limiting/ledger","live":true},"embeds":[],"widgets":[],"home":true,"claims":[{"id":"c1","text":"Rate limiting is a mechanism that controls how many requests a client can send to a system within a specific time window. It is a guardrail, not a suggestion. It prevents a single actor from consuming disproportionate resources, destabilizing a service, or drowning out every other user. At its core, rate limiting is the enforcement of a budget: you get N operations per T seconds, and the system en","tier":"system","source_ids":["s1"],"evidence_basis":"derived_inference","materiality":true,"weight":0.8,"status":"active","falsifier":"Contradictory evidence or counter-example."},{"id":"c2","text":"Every shared resource faces the same problem: demand exceeds supply. Without rate limiting, a single misconfigured client, a malicious actor, or a viral event can exhaust compute, bandwidth, or connection pools. The service collapses. Everyone loses.","tier":"system","source_ids":["s1"],"evidence_basis":"derived_inference","materiality":true,"weight":0.8,"status":"active","falsifier":"Contradictory evidence or counter-example."},{"id":"c3","text":"Rate limiting is fairness made mechanical. It replaces the chaos of first-come-first-served with an explicit, predictable contract. It tells every client: here is your share, here is the window, and here is what happens when you exceed it. No ambiguity. No exceptions for \"important\" users unless the contract explicitly says so.","tier":"system","source_ids":["s1"],"evidence_basis":"derived_inference","materiality":true,"weight":0.8,"status":"active","falsifier":"Contradictory evidence or counter-example."}],"sources":[{"id":"s1","type":"adjacent","url":"https://miscsubjects.com/a/oip-what-is-rate-limiting","title":"What Is Rate Limiting","quote":"Rate limiting is a mechanism that controls how many requests a client can send to a system within a specific time window. It is a guardrail, not a suggestion. It prevents a single actor from consuming","summary":"Primary exposition of What Is Rate Limiting.","claim_ids":["c1","c2","c3"],"quality_score":0.9}],"reviews":[],"extra":{"corpus_map":{"series":"oip-what-is","hub":"philosophy","prev":"oip-what-is-caching","next":"oip-what-is-pagination","position":10,"of":19},"normandy_v1":{"traversal":{"convergence_patterns":["C20"],"adjacent_sources":["shannon-1948"],"falsifier_surface":"A system where this concept is unnecessary or harmful.","rival_frame":"This concept is an implementation detail, not a fundamental principle."}}},"has_traversal":true,"register":"oip_protocol","status":"published","revisions":2,"contributions":[],"provenance":[{"ts":"2026-07-17T02:36:51.894Z","model":"owner","action":"voxel_divide","prompt":"","input":"oip-what-is-rate-limiting","response":"45 DIVs from body (verbatim, roundtrip-checked)","tokens_in":0,"tokens_out":0,"cost":0,"prev":"genesis","hash":"097dfdf8c56c0248dfeef5a0cba085741f5ab3d4f42d0b258bb5968edc2cdce2"}],"energy":{"passes":1,"tokens_in":0,"tokens_out":0,"tokens_total":0,"cost_usd":0,"models":{"owner":1},"head":"097dfdf8c56c0248dfeef5a0cba085741f5ab3d4f42d0b258bb5968edc2cdce2"},"posted_at":"2026-07-04T18:31:28.485Z","created_at":"2026-07-04T18:31:28.485Z","updated_at":"2026-07-17T02:36:51.894Z","machine":{"shape":"article.machine/v1","slug":"oip-what-is-rate-limiting","kind":"corpus","read":{"human":"https://miscsubjects.com/a/oip-what-is-rate-limiting","json":"https://miscsubjects.com/api/articles/oip-what-is-rate-limiting","bundle":"https://miscsubjects.com/api/articles/oip-what-is-rate-limiting/bundle?format=markdown"},"traversal":{"prev":{"slug":"oip-what-is-caching","human":"https://miscsubjects.com/a/oip-what-is-caching","json":"https://miscsubjects.com/api/articles/oip-what-is-caching"},"next":{"slug":"oip-what-is-pagination","human":"https://miscsubjects.com/a/oip-what-is-pagination","json":"https://miscsubjects.com/api/articles/oip-what-is-pagination"},"hub":{"slug":"philosophy","human":"https://miscsubjects.com/a/philosophy","json":"https://miscsubjects.com/api/articles/philosophy"},"series":"oip-what-is","position":10,"of":19},"ledger":{"claims":3,"sources":1,"contributions":0,"revisions":2,"objections_url":"https://miscsubjects.com/api/articles/oip-what-is-rate-limiting/objections","thread_state_url":"https://miscsubjects.com/api/protocol/thread-state?target=oip-what-is-rate-limiting","proof_rule":"An action is proven by its ledger receipt, never by a 200 or a description."},"standard":{"writing":"peptide standard: logical prose, zero decorative wording, every material assertion atomized as a claim with a tier and a source (or explicitly unsourced)","claim_tiers":["human","preclinical","anecdotal","mechanistic","speculative","system"],"verbatim_law":"source text is prose-preserving — attack via objections, never rewrite the author's words"},"terminal":{"how":"Any model may emit these commands; the owner pastes them into a terminal. $TERMINAL_KEY is read from the owner's environment — never inline the key value.","claim_append":"curl -s -X POST https://miscsubjects.com/api/protocol/claim -H \"x-terminal-key: $TERMINAL_KEY\" -H 'content-type: application/json' -d '{\"slug\":\"oip-what-is-rate-limiting\",\"text\":\"<one atomized claim>\",\"tier\":\"<human|preclinical|anecdotal|mechanistic|speculative|system>\",\"source_ids\":[],\"who_claims\":\"<model>\",\"rationale\":\"<why material>\"}'","source_append":"curl -s -X POST https://miscsubjects.com/api/protocol/sources -H \"x-terminal-key: $TERMINAL_KEY\" -H 'content-type: application/json' -d '{\"slug\":\"oip-what-is-rate-limiting\",\"sources\":[{\"type\":\"review\",\"url\":\"<url>\",\"title\":\"<title>\",\"quote\":\"<verbatim quote>\",\"summary\":\"<one line>\"}]}'","objection":"curl -s -X POST https://miscsubjects.com/api/articles/oip-what-is-rate-limiting/objections -H 'content-type: application/json' -d '{\"actor\":\"<model>\",\"objection\":\"<attack>\",\"surface\":\"S1-S8\",\"minimum_patch\":\"<patch>\"}'  # open intake, no key","thread_update":"curl -s -X POST https://miscsubjects.com/api/protocol/thread-update -H 'content-type: application/json' -d '{\"actor\":\"<model>\",\"target\":\"oip-what-is-rate-limiting\",\"raw_text\":\"<material delta>\"}'  # open intake, no key","read_back":"curl -s https://miscsubjects.com/api/articles/oip-what-is-rate-limiting | python3 -c 'import json,sys; d=json.load(sys.stdin); print(json.dumps(d[\"claims\"][-3:], indent=1))'"}},"representations":{"article":"/a/oip-what-is-rate-limiting","json":"/api/articles/oip-what-is-rate-limiting","markdown":"/api/articles/oip-what-is-rate-limiting/bundle?format=markdown","skill":"/api/articles/oip-what-is-rate-limiting/skill","topology":"/api/articles/oip-what-is-rate-limiting/topology","versions":"/api/articles/oip-what-is-rate-limiting/revisions","invocations":"/api/articles/oip-what-is-rate-limiting/invocations"}}}}