Erreurs & troubleshooting

Format commun des erreurs (RFC 7807)

Toutes les erreurs de l'API sont retournées au format standardisé Problem Details for HTTP APIs (RFC 7807). Cela garantit une structure JSON homogène et prévisible, facilitant la gestion des erreurs côté client.

{
  "type": "https://api.insurance-agg.example/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "La validation de la requête a échoué.",
  "instance": "/api/v1/partner/contracts/auto/classic",
  "requestId": "req_2026-04-24_001",
  "timestamp": "2026-04-25T14:30:00.000Z",
  "invalidParams": [
    "contract.pfs doit être supérieur à 125 pour la catégorie 550"
  ]
}

Codes HTTP

Erreurs fréquentes

400 — Configuration paiement manquante

{
  "type": "https://api.assurance.kiriku.app/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "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é

{
  "type": "https://api.assurance.kiriku.app/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "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

{
  "type": "https://api.assurance.kiriku.app/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "La validation de la requête a échoué.",
  "invalidParams": [
    "contract.pfs 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

{
  "type": "https://api.assurance.kiriku.app/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "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

{
  "type": "https://api.assurance.kiriku.app/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "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

{
  "type": "https://api.assurance.kiriku.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Paiement introuvable: AUTO_CLASSIC_1712345678901_ab12cd34ef56"
}

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)

{
  "type": "https://api.assurance.kiriku.app/errors/bad-gateway",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "Upstream provider returned an error",
  "extensions": { "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.