Erros

Todo erro tem o mesmo formato e um código estável. O seu sistema decide o que fazer pelo código, nunca pela mensagem.

Formato

{
  "erro": {
    "codigo": "ESCOPO_INSUFICIENTE",
    "mensagem": "Esta integração não tem a permissão pedidos:ler.",
    "escopoNecessario": "pedidos:ler",
    "detalhes": [],
    "requestId": "req_87da1622e9de4dd9b63e6cb2",
    "doc": "https://docs.otlshoes.com.br/erros#ESCOPO_INSUFICIENTE"
  }
}

Campo	Descrição
`codigo`	Identificador estável. É nele que o seu sistema faz o `switch`.
`mensagem`	Texto para gente ler. Pode mudar — não compare contra ele.
`detalhes`	Em erro de validação, um item por problema, com o `campo` quando houver.
`requestId`	O mesmo do cabeçalho `X-Request-Id`. Informe ao suporte.
`doc`	Link direto para a entrada deste código, nesta página.

Alguns códigos trazem campos a mais ao lado de codigo — por exemplo escopoNecessario emESCOPO_INSUFICIENTE. Novos códigos e campos podem ser acrescentados: trate o que você conhece e tenha um caminho padrão para o resto, decidido pelo status HTTP.

Autenticação (401)

Código	HTTP	O que significa	O que fazer
`TOKEN_INVALIDO`	401	Token de acesso ausente, inválido ou revogado.	Confira o header Authorization: Bearer <token>. Se o token foi revogado, peça um novo ao parceiro.
`TOKEN_EXPIRADO`	401	O token de acesso venceu.	O parceiro gera um novo token na mesma integração, em Integrações no painel.
`TOKEN_DE_OUTRO_AMBIENTE`	401	Este token é de outro ambiente.	Tokens otl_sbx_ só valem no sandbox e otl_prod_ só em produção. Confira a URL base.
`CONTA_DESATIVADA`	401	A conta do parceiro está desativada.	O parceiro deve falar com a equipe OTL.

Permissão e acesso (403)

Código	HTTP	O que significa	O que fazer
`TERMS_PENDING`	403	O parceiro precisa aceitar os Termos de Uso no painel para a integração continuar.	O aceite só pode ser feito pelo parceiro, no painel. A API volta na hora.
`TERMOS_API_PENDENTES`	403	O prazo para aceitar a versão nova dos Termos de Uso da API terminou.	O parceiro aceita os Termos da API em Integrações no painel. A API volta na hora.
`INTEGRACAO_SUSPENSA`	403	Esta integração foi suspensa pela equipe OTL.	O parceiro vê o motivo na aba Integrações do painel e fala com a equipe OTL. O token volta a funcionar quando a suspensão for retirada, sem troca.
`LOJA_HUB_NAO_LIBERADA`	403	A loja no HUB não está liberada para este parceiro.	O parceiro pede a liberação da loja à equipe OTL. Não depende das permissões da integração.
`API_NAO_LIBERADA`	403	A API não está liberada para este parceiro.	O parceiro solicita (ou religa) o acesso com a equipe OTL. Os tokens voltam a funcionar sem troca.
`ESCOPO_INSUFICIENTE`	403	Esta integração não tem a permissão necessária.	Veja `escopoNecessario` e peça ao parceiro para incluir a permissão na integração.
`ACESSO_NEGADO`	403	Acesso negado.	A operação não é permitida para este parceiro.

Requisição (400, 404, 409, 422)

Código	HTTP	O que significa	O que fazer
`HUB_NOT_READY`	400	A loja ainda não pode ser publicada.	Veja `publicacao` em GET /v1/loja-hub: falta o WhatsApp da loja (na ficha, pelo painel), o endereço ou ao menos um produto disponível.
`ROTA_NAO_ENCONTRADA`	404	Esta rota não existe na API.	Confira o método e o caminho na referência da documentação.
`NAO_ENCONTRADO`	404	Recurso não encontrado.	Confira o identificador. Recurso de outro parceiro também responde 404.
`REQUISICAO_INVALIDA`	400	A requisição não pôde ser entendida.	Confira o corpo e os parâmetros na referência do endpoint.
`VALIDACAO`	400	Um ou mais campos são inválidos.	Veja `detalhes`: cada item diz o campo e o problema.
`PARAMETRO_INVALIDO`	400	Parâmetro inválido.	Veja `detalhes` e a referência do endpoint.
`CURSOR_INVALIDO`	400	O cursor de paginação é inválido.	Use exatamente o `proximoCursor` da resposta anterior, sem alterar. Para recomeçar, omita o cursor.
`CONFLITO`	409	A operação conflita com o estado atual do recurso.	Leia o recurso de novo e refaça a operação.
`NAO_PROCESSAVEL`	422	A requisição é válida, mas não pôde ser processada.	Veja a mensagem e os detalhes.
`ITENS_INDISPONIVEIS`	422	Um ou mais itens não podem ser vendidos agora.	Veja `itens`: cada um traz o `indice` no corpo enviado, o `motivo` e o `disponivel`. Ajuste e envie de novo — nada foi criado.
`PROFILE_INCOMPLETE`	400	A ficha cadastral do parceiro está incompleta.	O parceiro completa os dados em Minha conta, no painel. `fichaCompleta` em GET /v1/conta mostra o estado.
`SUPERFRETE_NOT_CONNECTED`	400	O parceiro não tem conta SuperFrete conectada neste ambiente.	O parceiro conecta a conta dele em Etiquetas, no painel. GET /v1/superfrete mostra o estado.
`SALE_VALUE_REQUIRED`	400	Há item do pedido sem o valor de venda, que vai na declaração de conteúdo da etiqueta.	Informe o valor de venda de todos os itens (PATCH …/itens/{itemId}/valor-venda) e tente de novo.
`MIN_ITEMS_NOT_MET`	400	Pedidos para o endereço do próprio parceiro têm um mínimo de pares.	A mensagem diz o mínimo. Pedido com enviarPara: CLIENTE não tem mínimo.
`REFERENCIA_EXTERNA_DUPLICADA`	409	Já existe um pedido com esta referenciaExterna.	Não tente de novo: o pedido já foi criado. Veja `pedido` na resposta e consulte-o.
`IDEMPOTENCY_KEY_OBRIGATORIA`	400	Este endpoint exige o header Idempotency-Key.	Envie um identificador único por operação (um UUID serve) e repita o MESMO em caso de nova tentativa.
`IDEMPOTENCY_KEY_INVALIDA`	400	O header Idempotency-Key é inválido.	Use de 1 a 255 caracteres visíveis, sem espaços.
`IDEMPOTENCY_KEY_REUTILIZADA`	422	Esta Idempotency-Key já foi usada com um corpo diferente.	Cada operação nova precisa de uma chave nova. Só repita a chave ao repetir a MESMA requisição.
`REQUISICAO_EM_ANDAMENTO`	409	Uma requisição com esta Idempotency-Key ainda está sendo processada.	Aguarde alguns segundos e repita com a mesma chave: você receberá o resultado da primeira.

Limite (429)

Código	HTTP	O que significa	O que fazer
`LIMITE_EXCEDIDO`	429	Limite de requisições excedido.	Aguarde o número de segundos do header Retry-After antes de tentar de novo.

Servidor (500, 503)

Código	HTTP	O que significa	O que fazer
`SERVICO_INDISPONIVEL`	503	Serviço temporariamente indisponível.	Tente de novo em instantes, com a mesma Idempotency-Key.
`ERRO_INTERNO`	500	Erro interno. Já fomos avisados.	Tente de novo. Se persistir, envie o `requestId` ao suporte.

O que repetir e o que não repetir

429: espere os segundos do cabeçalho Retry-After e tente de novo.
500 e 503: tente de novo com espera crescente (1s, 2s, 4s…), no máximo algumas vezes.
400, 401, 403, 404, 409 e 422: repetir a mesma chamada dá o mesmo resultado. Corrija a causa antes.