Pular para o conteúdo principal

Códigos de erro

Formato da resposta de erro​

Todo erro tem o mesmo formato:

{
"status": 403,
"timestamp": "2026-11-17T14:30:00.000Z",
"path": "/external/v1/purchase-orders",
"errors": [],
"friendlyMessage": "Funcionalidade indisponível. O recurso que você acessou está indisponível no seu plano. Acione o time de suporte da plataforma!"
}
CampoTipoDescrição
statusnúmeroCódigo HTTP.
timestamptextoMomento do erro (ISO 8601).
pathtextoRota chamada.
errorstexto[]Detalhes técnicos, quando houver. Pode vir vazio.
friendlyMessagetextoMensagem legível, no idioma do cabeçalho locale (padrão: português). Pode ser mostrada ao usuário.
codetextoSó em alguns casos: código fixo para tratar no seu sistema (ex.: COMPANY_SESSION_EXPIRED).
detailsobjetoSó em alguns casos: dados extras que acompanham o code.

Trate os erros pelo status e, quando existir, pelo code. Não compare o texto da friendlyMessage: ele pode mudar.

Códigos de status​

CódigoQuando acontece
200Sucesso na consulta ou atualização. Na busca por ID, também quando o registro não existe (corpo {}; veja Paginação e filtros).
201Registro criado.
400Dados inválidos: campo obrigatório faltando, valor fora do permitido, filtro em relations com campo que não existe.
401Credenciais erradas no POST /external/v1/auth, ou accessToken ausente ou vencido.
402Assinatura da empresa suspensa: criações e atualizações são recusadas (code = SUBSCRIPTION_SUSPENDED); as leituras continuam funcionando.
403Recurso fora do plano da empresa, ação não permitida, sessão que não é a da API Key, registro de outra empresa numa atualização, ou sessão da empresa vencida (code = COMPANY_SESSION_EXPIRED).
404Registro inexistente numa atualização ou numa regra de negócio que procura outro registro.
409 / 422Conflito com o estado de outro registro (usados, por exemplo, nos pedidos de contratação).
429Limite de requisições excedido. Veja Rate limits.
500Erro inesperado. Tente de novo em alguns segundos; se persistir, abra um chamado com o X-Request-ID da resposta.
502Um serviço de terceiro usado pela operação falhou.

Erros comuns​

Autenticação (401 e 403)​

friendlyMessage ou codeCausaO que fazer
API Key inválida ou expirada.Chave errada ou revogada.Confira a chave; se foi revogada, gere outra.
Secret inválido ou credenciais de autenticação incorretas.Secret errado.Confira o Secret guardado na geração.
A conta de serviço está inativa. Gere uma nova API Key.A chave foi revogada.Gere uma chave nova.
401 sem mensagem de chaveaccessToken vencido ou ausente.Autentique de novo com POST /external/v1/auth.
code = COMPANY_SESSION_EXPIREDA sessão da empresa (companyToken) venceu ou não foi enviada.Autentique de novo e envie o x-company-token novo.
A API externa só aceita a sessão gerada pela API Key da empresa.Token de login de uma pessoa usado na API Externa.Use os tokens do POST /external/v1/auth.

Plano e permissão (403)​

friendlyMessageCausaO que fazer
Funcionalidade indisponível. O recurso que você acessou está indisponível no seu plano...A empresa não tem no plano o recurso daquela rota.Contrate o recurso ou fale com o suporte.
Operação não permitida. O seu perfil de usuário não possui permissão para executar esta ação.O perfil da conta de serviço não permite a ação (leitura, criação ou edição).Confira os perfis de acesso da empresa.

Com a assinatura da empresa suspensa, a integração fica só com leitura: criações e atualizações respondem 402 com code = SUBSCRIPTION_SUSPENDED até a fatura ser regularizada.

Limite (429)​

friendlyMessageCausaO que fazer
Limite de requisições excedido. Tente novamente em N segundos.A integração passou do limite de uso da conta.Espere e tente de novo com espera exponencial.

Boas práticas​

  1. Verifique o status antes de ler o corpo.
  2. Ao receber 401 ou COMPANY_SESSION_EXPIRED, autentique de novo e repita a requisição uma vez.
  3. Ao receber 429, espere e tente de novo (veja Rate limits).
  4. Registre status, path, friendlyMessage e o X-Request-ID para investigar depois.
  5. Em 500, espere pelo menos alguns segundos antes de tentar de novo.
Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.