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

# Erros

> Entenda o envelope de erro que a API do BoxHero retorna e como tratar os erros no seu código.

Quando uma requisição falha, a API do BoxHero responde com um status de erro HTTP e um único envelope de erro em 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 | Descrição |
| --- | --- |
| `id` | ID exclusivo do erro: `ex_` seguido de 32 caracteres hexadecimais em minúsculas. Informe-o ao entrar em contato com o suporte. |
| `type` | Código de erro estável e legível por máquina. Use-o para ramificar a lógica no seu código, e não o `title`. |
| `title` | Resumo legível por humanos, em inglês. O texto pode mudar. |
| `correlationID` | ID da requisição: `rq_` seguido de 32 caracteres hexadecimais em minúsculas, idêntico ao cabeçalho de resposta `X-Correlation-Id`. Nós o usamos para encontrar a sua requisição nos nossos logs. |
| `instance` | O recurso que falhou, por exemplo `/items/12345`. O caminho não tem o prefixo `/v1`. |
| `code` | Motivo detalhado do erro, por exemplo `tx-modify-revision-mismatch`. Nem sempre está presente. Ramifique primeiro por `type` e depois por `code` para um tratamento mais preciso. |
| `errors` | Detalhes por campo, presentes nas respostas `/errors/invalid-request` (`400`). Cada entrada tem um `path` que localiza o campo inválido e uma `message` legível por humanos. |

Alguns erros também incluem o id do recurso envolvido, como `item_id` ou `order_id`, como campos extras de nível superior.

> **Note**
>
> Você pode enviar o seu próprio cabeçalho de requisição `X-Correlation-Id` para conectar os seus rastreamentos aos nossos. O mesmo valor volta na resposta e em `correlationID`.

## Códigos de status comuns

| Status | Significado | O que fazer |
| --- | --- | --- |
| `400` | A requisição é inválida, ou o modo da equipe não oferece suporte a este endpoint | Corrija a requisição — `errors` lista os campos inválidos. Não tente novamente sem alterações. |
| `401` | O token de API está ausente ou é inválido | Verifique o cabeçalho `Authorization`. Consulte [Autenticação](https://www.boxhero.io/docs/pt/developers/api/authentication). |
| `403` | O BoxHero recusou a alteração — por exemplo, ela viola uma regra de estoque ou a `revision` enviada está desatualizada | Verifique `code` para saber o motivo. Corrija a requisição, ou busque os dados mais recentes, antes de tentar novamente. |
| `404` | O recurso não existe nesta equipe ou foi excluído | Verifique o id. Não tente novamente sem alterações. |
| `429` | Requisições demais | Aguarde e tente novamente. Consulte [Limite de requisições](https://www.boxhero.io/docs/pt/developers/api/rate-limiting). |

Os tipos de erro que cada endpoint pode retornar estão listados junto com ele na [Referência da API](https://www.boxhero.io/docs/pt/developers/api/reference).

## Como tratar um conflito de revisão

Para [atualizar](https://www.boxhero.io/docs/pt/developers/api/reference/transactions/update-transaction) ou [excluir](https://www.boxhero.io/docs/pt/developers/api/reference/transactions/delete-transaction) uma transação, envie a `revision` mais recente que você viu. Se outra pessoa alterou a transação nesse meio-tempo, a API rejeita a requisição com `403` e `code` definido como `tx-modify-revision-mismatch`. Ramifique por `code`: busque a transação novamente, confira a alteração e tente de novo com a nova `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.
  }
}
```