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:

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

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

Os tipos de erro que cada endpoint pode retornar estão listados junto com ele na Referência da API.

Como tratar um conflito de revisão

Para atualizar ou excluir 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.

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