Comprendre et traiter tous les codes d'erreur de l'API

Chaque réponse d'erreur de l'API Coffrify suit un format Stripe-style prévisible : un objet error imbriqué contenant un code machine-lisible, un message humain, un champ optionnel param (champ invalide) et un doc_url. Toutes les réponses incluent un header X-Request-Id pour corréler vos logs avec les traces Coffrify. En cas de doute, l'endpoint GET /v1/diagnostics/error/{code} fournit pour chaque code son explication complète, sa catégorie (tool_error, plan_or_quota, server_error) et ses étapes de résolution concrètes. En parallèle, GET /v1/status/services vous permet de vérifier l'état opérationnel de chaque composant Coffrify avant d'ouvrir un ticket support.

Authentification

Les deux endpoints de diagnostic nécessitent un header Authorization: Bearer <clé>. Les préfixes valides 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). La clé est validée pour le rate-limiting uniquement : aucun `requiredScope` n'est imposé sur ces endpoints. Un token avec un scope minimal comme transfers:read suffit.

Format standard d'une réponse d'erreur

Toutes les erreurs partagent cette enveloppe : un objet error avec un code stable (à tester) et un message lisible (à journaliser). Branchez votre logique sur le code, pas sur la chaîne du message.

{
  "error": {
    "code": "scope_missing",
    "message": "This token is missing the `transfers:write` scope. Granted scopes : transfers:read. Mint a new MCP token with the right scope at https://app.coffrify.com/mcp.",
    "param": null,
    "doc_url": "https://docs.coffrify.com/mcp/scopes"
  }
}

Catalogue des codes d'erreur

Le tableau ci-dessous recense les codes réellement renvoyés, leur statut HTTP et leur catégorie. Un même statut HTTP (par exemple 403) peut couvrir plusieurs code distincts, à traiter différemment.

Appeler le catalogue de diagnostic

Plutôt que de coder en dur ces explications, vous pouvez les obtenir à la volée via /v1/diagnostics/error/{code}. Les exemples ci-dessous montrent comment l'appeler.

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

Réponse du catalogue

La réponse fournit un title, une explication et des next_steps pour le code demandé. Idéal pour afficher un message d'aide contextuel à vos utilisateurs ou enrichir vos logs.

{
  "code": "scope_missing",
  "kind": "tool_error",
  "title": "Le token n'a pas le scope requis",
  "explanation": "L'endpoint demande un scope (ex: `transfers:write`) qui n'est pas accordé au token utilisé. Le token est valide mais ses permissions sont trop étroites pour cet appel.",
  "next_steps": [
    "Identifier le scope manquant dans le message de l'erreur 403",
    "Régénérer un token MCP avec ce scope coché : https://app.coffrify.com/mcp",
    "Mettre à jour la config du client (Claude / Cursor / Cline / Continue) avec le nouveau token"
  ],
  "docs_url": "https://docs.coffrify.com/mcp/scopes"
}

Headers de rate-limiting et de traçabilité

Au-delà du corps, plusieurs en-têtes accompagnent chaque réponse. Notez surtout X-Request-Id (à fournir au support) et les en-têtes de quota, listés ci-dessous.

Voir aussi

• Premiers pas avec l'API Coffrify
• Authentification et gestion des clés API
• Rate limiting et idempotence
• Scopes et permissions des tokens MCP
• Recevoir des événements avec les Webhooks
• Référence complète des erreurs