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 :

{
  "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.

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.
`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.

Les types d’erreurs que chaque endpoint peut renvoyer sont indiqués avec celui-ci dans la référence de l’API.

Gérer un conflit de révision

Pour mettre à jour ou supprimer 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.

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.
  }
}