Rate limiting

L'API Coffrify applique des limites de débit pour garantir la stabilité de la plateforme et une répartition équitable des ressources entre tous les comptes. Chaque réponse de l'API renvoie des en-têtes qui vous indiquent le nombre de requêtes restantes et le moment où votre quota se réinitialise. En lisant ces en-têtes et en réagissant correctement au code 429, vous gardez vos intégrations fiables sans jamais saturer l'API.

Comment fonctionne le rate limiting

Les limites s'appliquent par clé d'API. Chaque requête authentifiée consomme une unité de votre quota courant. Lorsque vous atteignez la limite, l'API cesse temporairement de traiter vos requêtes et répond avec le code 429 Too Many Requests jusqu'à la prochaine fenêtre de réinitialisation. Les requêtes au-delà de la limite ne sont pas mises en file d'attente : elles sont refusées immédiatement, vous devez donc les réessayer après le délai indiqué.

En-têtes de réponse

Toutes les réponses de l'API incluent un jeu d'en-têtes qui décrivent l'état de votre quota au moment de la requête. Lisez-les pour piloter le rythme de vos appels.

$ curl -i https://api.coffrify.com/v1/transfers \
    -H "Authorization: Bearer cof_live_..."
 
HTTP/2 200
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1749556800
X-RateLimit-Policy: 100;w=60

La réponse 429

Quand vous dépassez la limite, l'API renvoie le code 429 accompagné d'un corps d'erreur standard et de l'en-tête Retry-After. Le code d'erreur à tester est rate_limited.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry after the delay indicated by Retry-After.",
    "request_id": "req_8f3a2c1d9e"
  }
}

Lorsque vous recevez un 429, lisez l'en-tête Retry-After pour connaître le nombre de secondes à patienter, attendez ce délai, puis rejouez la requête. Ne réessayez jamais immédiatement : vous ne feriez que prolonger le blocage.

Gérer le 429 dans votre code

L'exemple suivant lit Retry-After, attend le délai demandé, puis relance l'appel. Prévoyez un nombre maximal de tentatives pour éviter une boucle infinie.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);
 
    if (res.status !== 429) {
      return res;
    }
 
    const retryAfter = Number(res.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
 
  throw new Error('Rate limit: nombre de tentatives dépassé');
}
 
const res = await fetchWithRetry('https://api.coffrify.com/v1/transfers', {
  headers: { Authorization: `Bearer ${process.env.COFFRIFY_API_KEY}` },
});

Rester sous la limite

Quelques pratiques simples vous évitent d'atteindre la limite en conditions normales.

• Surveillez X-RateLimit-Remaining et ralentissez le rythme dès qu'il approche de zéro, sans attendre le 429.
• Espacez vos requêtes plutôt que de les envoyer en rafale : préférez un débit régulier à des pics.
• Mettez en cache les réponses qui changent peu et ne les redemandez pas inutilement.
• Pour parcourir de grandes listes, utilisez la pagination par curseur (cursor, next_cursor) au lieu de boucler sur la totalité des pages d'un seul coup.
• Implémentez une réessai avec délai croissant (backoff) en plus de respecter Retry-After, afin de lisser la reprise après un pic.

En résumé : lisez les en-têtes X-RateLimit-* sur chaque réponse, testez le code d'erreur rate_limited sur les 429, et respectez toujours le délai de Retry-After avant de réessayer. Vos intégrations resteront ainsi fiables même sous forte charge.