Format des réponses

Toutes les réponses suivent les mêmes règles : JSON en UTF-8, codes HTTP standards, et une forme d'erreur unique.

Codes HTTP

Code	Signification	Que faire
200	Succès (lecture, vérification)
201	Créé (devis, souscription, paiement, contrat émis)
400	Requête mal formée	Corriger la requête.
401	Clé ou signature absente ou invalide	Vérifier la clé, le secret, l'horloge.
403	Action non autorisée pour votre compte (compte suspendu, offre, adresse IP, mode de paiement, plafond atteint)	Lire erreur.code : selon le cas, corriger l'appel ou contacter COVERAF.
404	Introuvable	Vérifier l'identifiant.
405	Méthode HTTP non prévue sur cette adresse	Vérifier GET ou POST.
409	L'état actuel ne permet pas l'action (déjà payée, paiement en cours, offre retirée...)	Relire l'état, puis agir.
410	Devis ou souscription expiré	Recommencer avec un nouveau devis.
422	Données refusées (saisie, éligibilité, montant)	Corriger d'après erreur.details.
429	Trop de requêtes	Réessayer plus tard.
500, 503	Erreur du service	Réessayer, avec la même Idempotency-Key.

En-têtes de réponse

En-tête	Contenu
`X-Request-Id`	Référence unique de l'appel (req_...). Notez-la dans vos journaux.
`X-Coveraf-Environnement`	`test` ou `live`.
`Idempotent-Replayed`	`true` si la réponse est rejouée (voir Idempotence).
`Content-Type`	`application/json; charset=utf-8`, ou `application/pdf` pour un document.

Forme d'une erreur

Toute erreur (4xx et 5xx) a la même forme. details n'est présent que pour une erreur de saisie, et liste chaque champ fautif :

Réponse 422

{
  "erreur": {
    "code": "validation",
    "message": "Certaines données sont manquantes ou incorrectes. Voir erreur.details.",
    "documentation": "https://docs.coveraf.com/erreurs#validation",
    "details": [
      {
        "champ": "assures[0].date_naissance",
        "message": "Date invalide, format attendu AAAA-MM-JJ."
      },
      {
        "champ": "assures[0].sexe",
        "message": "Valeur inconnue « H ». Valeurs possibles : M, F."
      }
    ]
  },
  "requete_id": "req_909aa466a35b048c634bdc80"
}

Champ	Rôle
`erreur.code`	Code stable, à utiliser dans votre code (liste complète dans Codes d'erreur).
`erreur.message`	Message en français, peut évoluer. Peut être montré à votre équipe, à reformuler pour vos clients.
`erreur.documentation`	Lien vers l'explication du code.
`erreur.details`	Pour validation : [{ champ, message }], avec le chemin exact du champ (assures[0].sexe).
`requete_id`	Même valeur que l'en-tête X-Request-Id.

Conventions

Montants : entiers en FCFA (XOF), sans décimales.
Dates : AAAA-MM-JJ. Instants : ISO 8601 en UTC (2026-11-04T13:38:53.411Z).
Absence de valeur : null, le champ reste présent.
Objets : chacun porte objet (devis, souscription, contrat, liste, evenement) et environnement.
Évolutions : de nouveaux champs peuvent apparaître dans les réponses sans changement de version. Ignorez ceux que vous ne connaissez pas.

Pagination

Les listes (aujourd'hui GET /v1/contrats) renvoient une page et une valeur suite. Pour la page suivante, rappelez avec ?avant= suivi de suite. suite: null : c'était la dernière page.

GET /v1/contrats?limite=10

{
  "objet": "liste",
  "donnees": [
    "…"
  ],
  "suite": "2026-11-04T16:44:34.688451+00:00"
}

À journaliser

Pour chaque appel en erreur, gardez requete_id, erreur.code et l'heure. Avec le requete_id, le support retrouve l'appel exact.