> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/fr/developers/api/errors.md).

# Erreurs

> Comprenez l’enveloppe d’erreur renvoyée par l’API BoxHero et comment traiter les erreurs dans votre code.

Lorsqu’une requête échoue, l’API BoxHero répond avec un statut d’erreur HTTP et une seule enveloppe d’erreur JSON :

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "type": "/errors/not-found",
  "title": "No item with id 12345 found in this team.",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "instance": "/items/12345"
}
```

## Champs

| Champ | Description |
| --- | --- |
| `id` | ID unique de l’erreur : `ex_` suivi de 32 caractères hexadécimaux en minuscules. Indiquez-le lorsque vous contactez le support. |
| `type` | Code d’erreur stable et lisible par une machine. Basez la logique de votre code sur ce champ, et non sur `title`. |
| `title` | Résumé lisible par un humain, en anglais. La formulation peut changer. |
| `correlationID` | ID de la requête : `rq_` suivi de 32 caractères hexadécimaux en minuscules, identique à l’en-tête de réponse `X-Correlation-Id`. Nous l’utilisons pour retrouver votre requête dans nos journaux. |
| `instance` | La ressource concernée par l’échec, par exemple `/items/12345`. Le chemin ne comporte pas le préfixe `/v1`. |
| `code` | Raison plus précise de l’erreur, par exemple `tx-modify-revision-mismatch`. Pas toujours présent. Basez-vous d’abord sur `type`, puis sur `code` pour un traitement plus fin. |
| `errors` | Détails au niveau des champs, présents dans les réponses `/errors/invalid-request` (`400`). Chaque entrée comporte un `path` qui localise le champ invalide et un `message` lisible par un humain. |

Certaines erreurs incluent également l’id de la ressource concernée, comme `item_id` ou `order_id`, sous forme de champs supplémentaires de premier niveau.

> **Note**
>
> Vous pouvez envoyer votre propre en-tête de requête `X-Correlation-Id` pour relier vos traces aux nôtres. La même valeur est renvoyée dans la réponse et dans `correlationID`.

## Codes de statut courants

| Statut | Signification | Que faire |
| --- | --- | --- |
| `400` | La requête est invalide, ou le mode de l’équipe ne prend pas en charge cet endpoint | Corrigez la requête — `errors` liste les champs invalides. Ne la renvoyez pas telle quelle. |
| `401` | Le jeton d’API est absent ou invalide | Vérifiez l’en-tête `Authorization`. Consultez [Authentification](https://www.boxhero.io/docs/fr/developers/api/authentication). |
| `403` | BoxHero a refusé la modification — par exemple, elle enfreint une règle de stock ou la `revision` envoyée est obsolète | Consultez `code` pour en connaître la raison. Corrigez la requête, ou récupérez les données les plus récentes, avant de réessayer. |
| `404` | La ressource n’existe pas dans cette équipe, ou a été supprimée | Vérifiez l’id. Ne renvoyez pas la requête telle quelle. |
| `429` | Trop de requêtes | Patientez, puis réessayez. Consultez [Limitation du débit](https://www.boxhero.io/docs/fr/developers/api/rate-limiting). |

Les types d’erreurs que chaque endpoint peut renvoyer sont indiqués avec celui-ci dans la [référence de l’API](https://www.boxhero.io/docs/fr/developers/api/reference).

## Gérer un conflit de révision

Pour [mettre à jour](https://www.boxhero.io/docs/fr/developers/api/reference/transactions/update-transaction) ou [supprimer](https://www.boxhero.io/docs/fr/developers/api/reference/transactions/delete-transaction) une transaction, envoyez la dernière `revision` que vous avez vue. Si quelqu’un d’autre a modifié la transaction entre-temps, l’API rejette la requête avec un `403` et `code` défini sur `tx-modify-revision-mismatch`. Basez-vous sur `code` : récupérez de nouveau la transaction, vérifiez la modification et réessayez avec la nouvelle `revision`.

```js
const res = await fetch(`https://rest.boxhero-app.com/v1/transactions/${id}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ revision, memo: "Recounted" }),
});

if (res.status === 403) {
  const error = await res.json();
  if (error.code === "tx-modify-revision-mismatch") {
    // Fetch the transaction again, check the change, then retry with its new revision.
  }
}
```