rate_limited

HTTP 429

When this happens

Each route in ROUTES declares its own per-minute request budget:

• POST /api/v1/intents: 30 requests / minute
• GET /api/v1/intents: 60 requests / minute
• GET /api/v1/intents/{id}: 120 requests / minute
• GET /api/v1/intents/{id}/origins: 120 requests / minute
• POST /api/v1/intents/{id}/source-inbox: 30 requests / minute

The budget is keyed by the authenticated key rather than by client IP address. It belongs to the credential the route declares it for, not to whatever network address sent the request. The check runs after authentication succeeds, so an unauthenticated caller cannot burn a route's budget probing it, and before the scope check.

The error envelope and headers

Every response on a rate-limited route carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, the seconds until the window resets. That holds for successes as well as errors, so a well-behaved caller can self-throttle before it ever sees a 429. The 429 response also carries Retry-After, the seconds to wait.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this route.",
    "request_id": "req_1a2b3c4d5e6f7a8b9c0d1e2f",
    "docs": "https://canopypay.io/errors/rate_limited"
  }
}

What to do about it

Wait at least Retry-After seconds, then retry. Once that wait has elapsed the retry is safe. For steady traffic, read RateLimit-Remaining on every response and slow down proactively rather than waiting to be refused.