Limites de débit

Capturia émet les headers RFC 9331 (`RateLimit-*`) sur toutes les responses, doublés des headers legacy `X-RateLimit-*` (sunset 2027-05-03). Body 429 enrichi avec un `limit_type` actionnable.

Politique

Scope	Fenêtre	Limite	Violation
Par clé API	`1h rolling`	100 requêtes	`429 rate_limit_exceeded` avec `details.limit_type: per_key` et `Retry-After`
Brute force par IP	`5 min`	10 tentatives clé invalide	`429 too_many_attempts` avec `details.limit_type: brute_force` et `Retry-After: 300`

Headers RFC 9331 (émis sur toutes les responses)

Header	Format	Exemple	Description
`RateLimit-Limit`	`int`	`100`	Quota actuel
`RateLimit-Remaining`	`int`	`87`	Requêtes restantes dans la fenêtre
`RateLimit-Reset`	`int (delta-seconds)`	`2415`	Secondes avant reset (entier)
`RateLimit-Policy`	`structured`	`100;w=3600`	Quota structuré (limite + fenêtre en secondes)

Headers legacy (sunset 2027-05-03)

Maintenus en parallèle des RFC 9331 pour ne pas casser les intégrations existantes. À retirer en /v2/.

Header	Format	Exemple	Description
`X-RateLimit-Limit`	`int`	`100`	Quota actuel
`X-RateLimit-Remaining`	`int`	`87`	Requêtes restantes
`X-RateLimit-Reset`	`ISO 8601`	`2026-05-04T11:00:00Z`	Timestamp absolu du reset

Body 429 enrichi

Le body d'un 429 rate_limit_exceeded contient un details.limit_type qui indique précisément quelle limite a été dépassée — utile pour ajuster ton retry strategy :

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit dépassé pour cette clé.",
    "hint": "Attends 2415 secondes avant de réessayer, ou réduis la fréquence des requêtes.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/rate-limits",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "per_key",
      "limit": 100,
      "count": 100,
      "retry_after_seconds": 2415
    }
  }
}

Header Retry-After

Header HTTP standard (RFC 7231) en secondes sur 429 et 503. Toujours respecter cette valeur avant de réessayer — un retry agressif peut prolonger ou amplifier le block.

503 Service Unavailable

Maintenance ou dégradation temporaire d'un service amont. Le header Retry-After est également présent. Aucune route v1 ne retourne 503 aujourd'hui — réservé pour cas futur (circuit-breaker, dépendance externe down).

Bonnes pratiques

Respecte Retry-After — ne retry pas avant la valeur indiquée.
Backoff exponentiel sur retry après 429 (e.g. 1s, 2s, 4s, 8s avec jitter).
Lis RateLimit-Remaining sur tes responses 200 pour anticiper le block (si < 10, slow down).
Distingue per_key vs brute_force — un brute_force = clé invalide, donc l'IP est blockée et changer de clé ne suffit pas.
Ne contourne pas via plusieurs IPs — Capturia détecte les patterns d'abus et peut suspendre la clé.