> ## Documentation Index
> Fetch the complete documentation index at: https://easybusinessdocumentation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Codes HTTP standards

> Comprendre les codes HTTP retournés par l'API et leur signification

L'API KAYBIC AFRICA utilise les codes HTTP classiques pour signaler l'état général d'une requête. Ces codes ne remplacent pas les erreurs métier, mais permettent d'identifier rapidement si la requête a été reçue et traitée correctement par le serveur.

## Codes principaux et signification

| Code    | Nom                   | Description / Exemple                                                                                                                              |
| ------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **200** | OK                    | La requête a été reçue et traitée avec succès. Exemple : initiation d'une transaction. La confirmation finale arrive via IPN.                      |
| **406** | Bad Request           | Cette erreur signifie qu'un champ requis n'a pas été saisi.                                                                                        |
| **401** | Unauthorized          | Clé API absente ou invalide. Vérifier la variable api\_key dans l'environnement Testeur d'API.                                                     |
| **422** | Request unprocessable | La requête ne peut pas être traitée. Par exemple vous pouvez avoir une erreur métier du type `destination field is not applicable`                 |
| **500** | Internal Server Error | Il s'agit ici d'une erreur côté serveur KAYBIC AFRICA. Et vous pouvez trouver des explications dans le champ `erreur` dans l'objet `response.data` |

## Erreurs métiers (probable de rencontrer dans les cas de bad request)

| Erreur                              | Code | Description                                                           |
| ----------------------------------- | ---- | --------------------------------------------------------------------- |
| destination field is not applicable | 422  | Le numéro du destinataire n'est probablement pas aligné à l'opérateur |
| amount is not applicable            | 422  | Le montant doit être un multiple de cinq (5) ou de cent (100).        |

## Bonnes pratiques liées aux codes HTTP

<CardGroup cols={2}>
  <Card title="Ne pas confondre HTTP et erreurs métier" icon="exclamation-triangle" color="#dc2626">
    HTTP 200 peut contenir un state: FAILED dans la réponse JSON si la
    transaction a échoué. Les champs state, `response`, et `error` doivent
    toujours être vérifiés après une réponse HTTP 200.
  </Card>

  <Card title="Gérer les erreurs réseau et serveur" icon="server" color="#1d60d5">
    Si l’API retourne une erreur 500 dans le cas d'un paiement (erreur interne
    du serveur), il est recommandé de relancer automatiquement la requête après
    un délai, en augmentant progressivement le temps d’attente entre chaque
    tentative (backoff progressif). Dans le cas d'un transfert, il recommandé de
    faire une vérification manuel avant de relancer la transaction.
  </Card>

  <Card title="Valider les entrées avant l'envoi" icon="check-circle" color="#16a34a">
    Vérifier les paramètres requis avant l'envoi de la requête surtout le
    `service_id` et votre `api_key`.
  </Card>

  <Card title="Journaliser les erreurs HTTP" icon="file-alt" color="#1d60d5">
    Conserver le transaction\_id, le code HTTP et le message de la réponse pour
    faciliter les réclamations.
  </Card>
</CardGroup>

<Info>
  Les codes HTTP indiquent l'état de la requête HTTP, pas nécessairement le
  résultat de la transaction. Toujours vérifier le champ `state` dans la réponse
  JSON pour connaître le statut réel de la transaction.
</Info>

<Tip>
  Implémentez une gestion d'erreurs robuste qui traite à la fois les codes HTTP
  et les erreurs métier dans la réponse JSON.
</Tip>