Erreurs & troubleshooting

Format commun des erreurs

Toutes les erreurs retournent une enveloppe JSON homogène :

{
  "error": {
    "code": "validation_failed",
    "message": "Le payload de demande de contrat est invalide",
    "requestId": "req_2026-04-24_001",
    "details": {
      "field": "contract.pfs",
      "reason": "Doit etre > 125 pour cat=550 et scatCode=011"
    }
  }
}

Codes HTTP

Erreurs fréquentes

400 — Configuration paiement manquante

{
  "error": {
    "code": "dexpay_config_missing",
    "message": "La configuration interne du paiement n'est pas active"
  }
}

Cause : côté plateforme, la configuration interne de paiement est incomplète.

Action partenaire : contacter le support. Ce n'est pas une erreur d'intégration côté partenaire.

401 — Non authentifié

{
  "error": { "code": "unauthorized", "message": "Invalid or missing API key" }
}

Causes :

• x-api-key absent.
• Clé révoquée ou expirée.
• Mélange environnement (clé sandbox utilisée en production ou inversement).

422 — Validation métier refusée

{
  "error": {
    "code": "validation_failed",
    "message": "Le payload de demande de contrat est invalide",
    "details": {
      "field": "contract.pfs",
      "reason": "Doit etre > 125 pour cat=550 et scatCode=011"
    }
  }
}

Causes possibles :

• cat=550 + scatCode=011 avec pfs <= 125
• cat=550 + scatCode=010 avec pfs > 125
• URL de retour manquante ou invalide
• champ obligatoire ASKIA absent ou mal formate

403 — Interdit : /contracts/auto/* appelé par un partenaire

{
  "error": {
    "code": "forbidden",
    "message": "Direct contract creation is not permitted for partner role. Use the payment-first flow."
  }
}

Cause : tentative d'appel direct à POST /contracts/auto/classic ou assimilé avec une clé API de rôle partner.

Action : migrer vers POST /api/v1/partner/contracts/auto/classic.

403 — Ressource appartenant à un autre partenaire

{
  "error": { "code": "forbidden", "message": "Resource not owned by this partner" }
}

Cause : tentative d'accéder à une reference créée par un autre compte partenaire.

Action : verifier la provenance de la reference et l environnement utilise.

404 — Référence inconnue

{
  "error": { "code": "reference_not_found", "message": "Unknown reference" }
}

Causes possibles :

• Typo sur la reference.
• Utilisation de la reference sandbox en production (et vice-versa).
• Purge (les références non-payées peuvent être purgées après un délai long).

502 — Erreur provider (paiement ou ASKIA)

{
  "error": {
    "code": "provider_upstream_error",
    "message": "Upstream provider returned an error",
    "details": { "provider": "dexpay", "upstreamStatus": 503 }
  }
}

Action : retenter avec backoff exponentiel. Si persistant, escalader au support.

Cas métier : paiement complété mais émission échouée

Comment le détecter

Vous le détectez par l'un des deux signaux suivants :

1. Réception d'un webhook insurance.contract.issuance_failed.
2. Appel GET /api/v1/partner/contracts/requests/:reference retournant contractStatus = ISSUANCE_FAILED.

Que faire

1. Ne pas rembourser automatiquement. L'agrégateur peut rejouer l'émission.
2. Créer un ticket support contenant :
   • la reference,
   • le requestId de la réponse,
   • la valeur de issuance.errorCode.
3. Informer l'utilisateur d'un "traitement en cours" (UX recommandée : ne pas afficher "paiement échoué", ce qui serait faux).
4. L'opérateur admin déclenchera un rejeu ; vous recevrez un nouveau webhook insurance.contract.issued si le rejeu aboutit.

Checklist de diagnostic

Avant d'ouvrir un ticket, valider dans cet ordre :

1. Clé API

   Est-elle bien celle de l'environnement appelé ? (sandbox ≠ prod).

2. Headers

   x-api-key, Content-Type: application/json, x-request-id présents ?

3. Idempotency

   Le même idempotency-key est-il réutilisé avec un body différent ? (409).

4. Payload contrat

   contract, returnUrl et cancelUrl sont-ils complets et coherents avec les regles metier ?

5. URLs

   returnUrl, cancelUrl, webhookUrl en HTTPS et publiques ?

6. Webhook

   Votre endpoint répond 2xx en < 5s ? La signature est-elle vérifiée ?

7. Logs

   Conservez x-request-id dans les logs partenaire — indispensable au support.

Contact support

Tout ticket doit contenir :

• l'environnement (sandbox / production),
• la ou les reference concernées,
• les requestId des réponses,
• un extrait de logs côté partenaire (avec timestamps UTC),
• la fenêtre temporelle de l'incident.