Référence des codes d'erreur

Toutes les réponses d'erreur de l'API REST Coffrify partagent une structure unique et un comportement prévisible. Quel que soit l'endpoint appelé, une requête qui échoue renvoie un code HTTP cohérent avec la nature du problème et un corps JSON décrivant précisément la cause. Cette page documente cette structure, la liste des codes HTTP que vous pouvez recevoir, les codes applicatifs textuels qui les accompagnent, et la réaction recommandée pour chacun. Elle vous sert de référence lorsque vous écrivez la logique de gestion d'erreurs de votre intégration.

Structure d'une erreur

Toute réponse en échec renvoie un objet JSON contenant une seule clé racine error. Cet objet expose trois champs : code (un identifiant textuel stable, fait pour être testé dans votre code), message (une phrase lisible décrivant le problème, destinée aux logs et au débogage) et request_id (l'identifiant unique de la requête, à fournir au support pour toute investigation). Branchez votre logique métier sur code, jamais sur le texte de message, qui peut évoluer.

{
  "error": {
    "code": "scope_missing",
    "message": "This endpoint requires the transfers:write scope.",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

Codes HTTP

Le code HTTP de la réponse indique la grande famille du problème. La règle générale est classique : les codes 4xx signalent une erreur de votre côté (requête à corriger avant de réessayer), les codes 5xx signalent un incident côté Coffrify (l'appel pourra être rejoué tel quel). Le tableau ci-dessous récapitule les codes que l'API peut renvoyer.

Codes applicatifs

Le champ code du corps précise la cause exacte, plus finement que le code HTTP. C'est sur cette valeur que vous devez construire votre logique de gestion d'erreurs, car elle est stable dans le temps. Le tableau suivant liste les codes applicatifs principaux, le code HTTP associé et la réaction attendue.

Erreurs d'idempotence

Lorsque vous fournissez un en-tête Idempotency-Key sur une écriture, deux situations particulières produisent un code HTTP 409. Avec le code idempotency_conflict, la même clé a déjà servi pour une requête dont le corps était différent : générez alors une nouvelle clé pour cette nouvelle requête. À l'inverse, un rejeu réussi (même clé, même corps) ne renvoie pas d'erreur : vous recevez la réponse d'origine, accompagnée de l'en-tête X-Coffrify-Idempotent-Replay: true qui signale qu'aucune nouvelle opération n'a été effectuée.

$ curl -i https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_..." \
  -H "Idempotency-Key: 9f1c2b7a-3d4e-5f60-8a90-1b2c3d4e5f60" \
  -d '{ ... }'
 
HTTP/2 409
Content-Type: application/json
 
{"error":{"code":"idempotency_conflict","message":"An Idempotency-Key was provided that matches a previous request with a different body. Use a fresh Idempotency-Key for new requests.","request_id":"req_7f8e9d0c1b2a"}}

Lire les en-têtes de débit

Sur un code 429, l'en-tête Retry-After indique le nombre de secondes à attendre avant de réessayer. Sans attendre l'erreur, chaque réponse renvoie aussi les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset et X-RateLimit-Policy, qui vous permettent d'anticiper et de lisser votre cadence d'appels.

async function callWithRetry(url, options, max = 5) {
  for (let attempt = 0; attempt < max; attempt++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") ?? 1);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (res.status >= 500) {
      // Incident côté Coffrify : repli exponentiel
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    const body = await res.json();
    if (!res.ok) {
      // Branchez votre logique sur body.error.code
      throw new Error(`${body.error.code}: ${body.error.message}`);
    }
    return body;
  }
  throw new Error("Nombre maximal de tentatives atteint");
}

Bonnes pratiques de gestion

• Testez error.code plutôt que le texte de error.message : seul le code est stable dans le temps.
• Sur 429 et 5xx, mettez en place des nouvelles tentatives automatiques (repli exponentiel pour les 5xx, respect de Retry-After pour les 429).
• Ne rejouez jamais une 400, 401, 403, 404, 413 ou 422 à l'identique : corrigez d'abord la requête.
• Conservez systématiquement request_id dans vos logs et transmettez-le au support pour toute investigation.
• Pour les écritures, utilisez une Idempotency-Key de 8 à 255 caractères et générez-en une nouvelle dès que le corps de la requête change.