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

# Gestion des erreurs

> Comment interpréter et gérer les erreurs de l'API Paps

L'API Paps retourne deux formats d'erreur selon le type de problème rencontré.

## Erreurs métier

Les erreurs de validation ou de traitement suivent l'enveloppe commune décrite dans [Format des réponses](/api-responses). Le champ `error` contient un message ou un nom d'exception sous forme de texte libre.

```json theme={null}
{
  "code": 400,
  "message": "Bad Request",
  "error": "Adresse de livraison invalide",
  "data": null
}
```

| Code  | Cas typique                                           |
| ----- | ----------------------------------------------------- |
| `400` | Requête invalide (paramètres manquants ou incorrects) |
| `404` | Ressource introuvable (colis, commande)               |
| `500` | Erreur réseau ou technique côté serveur               |

## Erreurs d'authentification

Les erreurs d'authentification (`x-api-key` invalide ou manquante) ne suivent pas l'enveloppe standard : elles sont renvoyées directement par le framework, avec un format différent.

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}
```

<Warning>
  Distinguez ces deux formats dans votre gestion d'erreurs : le premier utilise `code`/`error`/`data`, le second utilise `statusCode`/`message`/`error` sans enveloppe `data`.
</Warning>

## Bonnes pratiques

<Steps>
  <Step title="Distinguez les deux formats">
    Vérifiez la présence de `statusCode` pour identifier une erreur d'authentification, ou de `code` pour une erreur métier standard.
  </Step>

  <Step title="Journalisez le champ error">
    Conservez le contenu de `error` dans vos logs pour faciliter le diagnostic avec le support Paps.
  </Step>

  <Step title="Implémentez une stratégie de nouvelle tentative">
    Pour les erreurs `500`, prévoyez un mécanisme de retry avec backoff exponentiel.
  </Step>
</Steps>