> 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/es/developers/api/errors.md).

# 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:

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

> **Note**
>
> Puede enviar su propio encabezado de solicitud `X-Correlation-Id` para vincular sus trazas con las nuestras. El mismo valor se devuelve en la respuesta y en `correlationID`.

## 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](https://www.boxhero.io/docs/es/developers/api/authentication). |
| `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](https://www.boxhero.io/docs/es/developers/api/rate-limiting). |

Los tipos de error que puede devolver cada endpoint se indican junto a él en la [referencia de la API](https://www.boxhero.io/docs/es/developers/api/reference).

## Cómo gestionar un conflicto de revisión

Para [actualizar](https://www.boxhero.io/docs/es/developers/api/reference/transactions/update-transaction) o [eliminar](https://www.boxhero.io/docs/es/developers/api/reference/transactions/delete-transaction) 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`.

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