Errores

Conozca el objeto de error que devuelve la API de BoxHero y cómo gestionar los errores en su código.

Cuando una solicitud falla, la API de BoxHero responde con un código de estado de error HTTP y un único objeto de error JSON:

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

Campos

Campo	Descripción
`id`	ID único del error: `ex_` seguido de 32 caracteres hexadecimales en minúsculas. Inclúyalo cuando contacte con soporte.
`type`	Código de error estable y legible por máquinas. Base la lógica de su código en este campo, no en `title`.
`title`	Resumen legible para personas, en inglés. El texto puede cambiar.
`correlationID`	ID de la solicitud: `rq_` seguido de 32 caracteres hexadecimales en minúsculas, idéntico al encabezado de respuesta `X-Correlation-Id`. Lo usamos para encontrar su solicitud en nuestros registros.
`instance`	El recurso que falló, por ejemplo `/items/12345`. La ruta no incluye el prefijo `/v1`.
`code`	Motivo más concreto del error, por ejemplo `tx-modify-revision-mismatch`. No siempre está presente. Base su lógica primero en `type` y luego en `code` para un manejo más detallado.
`errors`	Detalles por campo, presentes en las respuestas `/errors/invalid-request` (`400`). Cada entrada tiene un `path` que indica el campo no válido y un `message` legible para personas.

Algunos errores también incluyen el id del recurso afectado, como item_id u order_id, como campos adicionales de nivel superior.

Códigos de estado habituales

Estado	Significado	Qué hacer
`400`	La solicitud no es válida, o el modo del equipo no admite este endpoint	Corrija la solicitud; `errors` indica los campos no válidos. No la reintente sin cambios.
`401`	Falta el token de API o no es válido	Compruebe el encabezado `Authorization`. Consulte Autenticación.
`403`	BoxHero rechazó el cambio; por ejemplo, infringe una regla de inventario o la `revision` enviada está desactualizada	Consulte `code` para saber el motivo. Corrija la solicitud u obtenga los datos más recientes antes de reintentar.
`404`	El recurso no existe en este equipo o se eliminó	Compruebe el id. No la reintente sin cambios.
`429`	Demasiadas solicitudes	Espere y vuelva a intentarlo. Consulte Límite de solicitudes.

Los tipos de error que puede devolver cada endpoint se indican junto a él en la referencia de la API.

Cómo gestionar un conflicto de revisión

Para actualizar o eliminar una transacción, envíe la revision más reciente que haya visto. Si otra persona modificó la transacción mientras tanto, la API rechaza la solicitud con un 403 y code igual a tx-modify-revision-mismatch. Base su lógica en code: vuelva a obtener la transacción, revise el cambio y reintente con la nueva 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.
  }
}