Mental model
Core concepts
x429 is small on purpose: a response shape, a signed ticket, a redemption header, and a client policy loop.
The problem x429 solves
A normal 429 says "not now" but gives no binding commitment. Agents either retry too fast, retry too late, or spend compute guessing. x429 changes the failure into a scheduled outcome.
Advisory retry
Retry-After is a hint. It does not reserve capacity and does not prevent a second collision when clients return.
Signed ticket
An x429 ticket is a cryptographic commitment scoped to a resource, client binding, and time window.
Vocabulary
| Term | Meaning |
|---|---|
| Origin | The API or service protecting a scarce endpoint. |
| Resource | The method/path or logical resource that capacity is assigned to, such as GET /v1/infer. |
| Ticket | A signed object that describes who can redeem, when, and for what. |
| Slot | The future admission window described by notBefore and notAfter. |
| Binding | A pseudonymous client identifier that prevents another party from stealing the ticket. |
| Nonce | A single-use replay guard. Once spent, the ticket cannot be redeemed again. |
| Upgrade | An optional earlier admission class, usually paid. |
| Discovery | The /.well-known/x429.json document that publishes keys and capabilities. |
Compatibility rule
Every x429 response must still be a valid HTTP 429. Legacy clients should not break; they see Retry-After and back off. Capable clients get determinism.
HTTP/1.1 429 Too Many Requests
Retry-After: 10
X429-Version: 1What x429 does not do
- It does not identify humans.
- It does not detect bots.
- It does not replace x402 or any payment rail.
- It does not promise fairness by itself. Fairness needs queue policy and, later, transparency logs.
- It does not make infinite capacity. It makes scarcity explicit and schedulable.