Gérer les erreurs et les retries automatiques dans le SDK

L'API Coffrify suit une convention d'erreur uniforme inspirée de Stripe : toute réponse non-2xx contient un objet error avec un code machine-lisible, un message humain et, le cas échéant, un param (champ invalide), des details et un doc_url. Le handler withApiHandler applique ce format à tous les endpoints et expose systématiquement les headers de rate-limit : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Policy (format <limite>;w=60). En cas de 429, le header Retry-After indique le nombre de secondes à attendre. Deux endpoints spécialisés complètent cet outillage : GET /v1/diagnostics/error/:code pour obtenir la documentation d'un code d'erreur, et GET /v1/status/services pour connaître l'état opérationnel de chaque service.

Authentification

Ces deux endpoints acceptent une clé API valide dans l'en-tête Authorization: Bearer <clé>. Les préfixes reconnus sont cof_live_…, cof_test_…, cof_sandbox_… (clés complètes), cof_rk_live_… / cof_rk_test_… (clés restreintes) et cof_mcp_live_… / cof_mcp_test_… (tokens MCP). Aucun scope particulier n'est requis pour ces deux endpoints : la clé sert uniquement au passage par le rate-limiter.

Structure d'une réponse d'erreur

Toutes les erreurs partagent la même enveloppe : un objet error contenant un code stable (à tester dans votre logique) et un message lisible (à journaliser, pas à analyser). Le statut HTTP indique la famille, le code la cause précise.

// Exemple : scope manquant (HTTP 403)
{
  "error": {
    "code": "scope_missing",
    "message": "This token is missing the `transfers:write` scope. Granted scopes : transfers:read.",
    "doc_url": "https://docs.coffrify.com/mcp/scopes"
  }
}
 
// Le header X-Request-Id est toujours présent
// X-Request-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
// X-Coffrify-Api-Version: 2026-05-14

Codes d'erreur réels

Le tableau ci-dessous liste les codes réellement renvoyés par l'API, leur statut HTTP et la marche à suivre. Distinguez les erreurs définitives (4xx, à corriger côté client) des erreurs transitoires (429, 5xx) qui justifient un retry.

Interroger le catalogue d'erreurs

L'endpoint /v1/diagnostics/error/{code} renvoie la documentation enrichie d'un code donné (explication, étapes de résolution). Pratique pour afficher un message d'aide contextuel ou enrichir vos logs.

curl -s https://api.coffrify.com/v1/diagnostics/error/scope_missing \
  -H "Authorization: Bearer cof_live_VOTRE_CLE" | jq .

Implémenter un retry avec backoff exponentiel

Ne réessayez que les erreurs transitoires, et toujours avec un backoff exponentiel agrémenté d'un jitter, en respectant l'en-tête Retry-After lorsqu'il est présent. L'exemple ci-dessous implémente ce schéma dans chaque langage.

#!/usr/bin/env bash
MAX_RETRIES=4
DELAY=1
 
for i in $(seq 1 $MAX_RETRIES); do
  RESP=$(curl -s -w "\n%{http_code}" \
    -H "Authorization: Bearer cof_live_VOTRE_CLE" \
    https://api.coffrify.com/v1/diagnostics/error/scope_missing)
  HTTP_CODE=$(echo "$RESP" | tail -1)
 
  if [ "$HTTP_CODE" -ne 429 ] && [ "$HTTP_CODE" -lt 500 ]; then
    echo "$RESP" | head -n -1
    break
  fi
 
  echo "Tentative $i : HTTP $HTTP_CODE - attente ${DELAY}s"
  sleep $DELAY
  DELAY=$((DELAY * 2))
done

Voir aussi

• Authentification et clés API
• Rate limits et quotas
• Idempotence des requêtes POST
• Superviser l'état des services en temps réel
• Webhooks et événements api_key.expired
• Premiers pas avec le SDK Node