Rate limits

Capturia emits RFC 9331 headers (`RateLimit-*`) on all responses, paired with legacy `X-RateLimit-*` headers (sunset 2027-05-03). Enriched 429 body with actionable `limit_type`.

Policy

Scope	Window	Limit	Violation
Per API key	`1h rolling`	100 requests	`429 rate_limit_exceeded` with `details.limit_type: per_key` and `Retry-After`
Brute force per IP	`5 min`	10 invalid-key attempts	`429 too_many_attempts` with `details.limit_type: brute_force` and `Retry-After: 300`

RFC 9331 headers (emitted on all responses)

Header	Format	Example	Description
`RateLimit-Limit`	`int`	`100`	Current quota
`RateLimit-Remaining`	`int`	`87`	Remaining requests in the window
`RateLimit-Reset`	`int (delta-seconds)`	`2415`	Seconds until reset (integer)
`RateLimit-Policy`	`structured`	`100;w=3600`	Structured quota (limit + window in seconds)

Legacy headers (sunset 2027-05-03)

Kept alongside RFC 9331 to avoid breaking existing integrations. Removed in /v2/.

Header	Format	Example	Description
`X-RateLimit-Limit`	`int`	`100`	Current quota
`X-RateLimit-Remaining`	`int`	`87`	Remaining requests
`X-RateLimit-Reset`	`ISO 8601`	`2026-05-04T11:00:00Z`	Absolute reset timestamp

Enriched 429 body

The body of a 429 rate_limit_exceeded includes a details.limit_type that precisely indicates which limit was hit — useful to adjust your retry strategy:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for this key.",
    "hint": "Wait 2415 seconds before retrying, or reduce request frequency.",
    "doc_url": "https://capturia.io/en/developers/api/v1/rate-limits",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "per_key",
      "limit": 100,
      "count": 100,
      "retry_after_seconds": 2415
    }
  }
}

Retry-After header

Standard HTTP header (RFC 7231) in seconds on 429 and 503. Always respect this value before retrying — aggressive retry can prolong or amplify the block.

503 Service Unavailable

Maintenance or temporary degradation of an upstream service. The Retry-After header is also present. No v1 route returns 503 today — reserved for future cases (circuit-breaker, external dep down).

Best practices

Respect Retry-After — do not retry before the indicated value.
Exponential backoff on retry after 429 (e.g. 1s, 2s, 4s, 8s with jitter).
Read RateLimit-Remaining on your 200 responses to anticipate the block (if < 10, slow down).
Distinguish per_key vs brute_force — brute_force means invalid key, so the IP is blocked and switching keys won't help.
Do not bypass via multiple IPs — Capturia detects abuse patterns and may suspend the key.