Gestion des erreurs

L'API Coffrify renvoie une réponse d'erreur cohérente quel que soit l'appel concerné. Chaque erreur arrive avec un code HTTP standard, un corps JSON structuré et un identifiant de requête que vous pouvez consigner et nous transmettre. Cette page décrit le format exact des erreurs, la liste des codes que vous rencontrerez, la manière de réagir à chacun, et les bonnes pratiques pour rendre votre intégration robuste.

Structure d'une erreur

Toutes les erreurs partagent la même enveloppe JSON. L'objet error contient trois champs : code (une chaîne stable, conçue pour être testée par votre code), message (un libellé lisible, destiné aux journaux et au débogage, susceptible d'évoluer) et request_id (l'identifiant unique de la requête).

{
  "error": {
    "code": "validation_error",
    "message": "The field 'files' is required.",
    "request_id": "req_8f3k2j9d1a"
  }
}

Conservez toujours le request_id

Le champ request_id identifie de façon unique l'appel ayant échoué. Consignez-le systématiquement dans vos journaux, et joignez-le à toute demande d'assistance : il nous permet de retrouver immédiatement la requête concernée et de diagnostiquer le problème, sans avoir à exposer le contenu de vos fichiers ni vos clés.

const res = await fetch("https://api.coffrify.com/v1/transfers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COFFRIFY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ files: [{ name: "contrat.pdf", size: 482910, mime_type: "application/pdf" }] }),
});
 
if (!res.ok) {
  const { error } = await res.json();
  console.error(`Coffrify error ${error.code} (request ${error.request_id}): ${error.message}`);
}

Codes d'erreur

Le tableau ci-dessous récapitule les codes que vous pouvez recevoir, le code HTTP associé et l'action attendue de votre côté. Chaque code est ensuite détaillé.

invalid_api_key

La clé est absente, mal formée, révoquée ou ne correspond pas à l'environnement visé. Vérifiez que l'en-tête est bien au format Authorization: Bearer cof_live_…, que la clé n'a pas été régénérée, et que vous utilisez le bon préfixe : cof_live_ en production, cof_test_ en test, cof_sandbox_ en bac à sable. Il s'agit d'une erreur de configuration : un nouvel essai à l'identique échouera, n'enclenchez pas de relance automatique.

scope_missing

La clé est valide mais ne dispose pas du scope nécessaire à l'opération. Par exemple, créer un transfert exige transfers:write, lister des collections exige collections:read. Ajoutez le scope manquant à la clé depuis votre espace, ou utilisez une clé qui en dispose. Comme pour une clé invalide, ne réessayez pas tel quel : il faut d'abord corriger les autorisations.

validation_error

Le corps de la requête est invalide : champ obligatoire manquant, type incorrect, valeur hors limites. Le message précise le champ en cause. Corrigez la charge utile avant de renvoyer la requête ; une relance automatique à l'identique renverra la même erreur.

not_found

La ressource ciblée n'existe pas, ou n'est pas accessible avec cette clé. Cela arrive typiquement sur GET /v1/transfers/{id} ou DELETE /v1/transfers/{id} avec un identifiant erroné, déjà supprimé ou expiré. Vérifiez l'identifiant et l'environnement de la clé. Inutile de réessayer sans changer l'identifiant.

rate_limited

Vous avez dépassé la limite de débit autorisée. La réponse est accompagnée de l'en-tête Retry-After (en secondes) ainsi que des en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset et X-RateLimit-Policy. Contrairement aux autres, cette erreur est temporaire : attendez la durée indiquée par Retry-After avant de réessayer, idéalement avec un repli exponentiel. Surveillez X-RateLimit-Remaining pour ralentir avant d'atteindre la limite.

idempotency_conflict

Vous avez réutilisé une Idempotency-Key déjà employée, mais avec un corps de requête différent. L'API refuse alors l'opération avec un code 409 pour éviter toute ambiguïté. Pour rejouer en sécurité une requête, renvoyez exactement le même corps avec la même clé : vous obtiendrez la réponse d'origine, accompagnée de l'en-tête X-Coffrify-Idempotent-Replay: true. Pour une opération réellement nouvelle, générez une Idempotency-Key différente.

Réessayer correctement

Toutes les erreurs ne se relancent pas. Distinguez les erreurs définitives (invalid_api_key, scope_missing, validation_error, not_found, idempotency_conflict) qui exigent une correction de votre côté, des erreurs transitoires (rate_limited, ou un code 5xx ponctuel) qui justifient une nouvelle tentative. Pour les secondes, attachez une Idempotency-Key à vos écritures et appliquez un repli exponentiel afin de ne jamais créer de doublon en cas de relance.

async function createTransfer(body, key) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch("https://api.coffrify.com/v1/transfers", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.COFFRIFY_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": key,
      },
      body: JSON.stringify(body),
    });
 
    if (res.ok) return res.json();
 
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") ?? 2 ** attempt);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
 
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
  }
  throw new Error("Coffrify: limite de tentatives atteinte");
}

Tester vos erreurs en bac à sable

Avant de passer en production, validez vos chemins d'erreur avec une clé cof_sandbox_. L'environnement bac à sable est isolé, réinitialisé après 24 heures et hors facturation. Ses garde-fous (10 Mo par fichier, 10 fichiers, 25 transferts par 24 h, 5 téléchargements) vous permettent par exemple de provoquer volontairement un rate_limited ou un validation_error et de vérifier que votre code réagit comme prévu.