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!"
}
| Campo | Tipo | Descrição |
|---|---|---|
status | número | Código HTTP. |
timestamp | texto | Momento do erro (ISO 8601). |
path | texto | Rota chamada. |
errors | texto[] | Detalhes técnicos, quando houver. Pode vir vazio. |
friendlyMessage | texto | Mensagem legível, no idioma do cabeçalho locale (padrão: português). Pode ser mostrada ao usuário. |
code | texto | Só em alguns casos: código fixo para tratar no seu sistema (ex.: COMPANY_SESSION_EXPIRED). |
details | objeto | Só 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ódigo | Quando acontece |
|---|---|
200 | Sucesso na consulta ou atualização. Na busca por ID, também quando o registro não existe (corpo {}; veja Paginação e filtros). |
201 | Registro criado. |
400 | Dados inválidos: campo obrigatório faltando, valor fora do permitido, filtro em relations com campo que não existe. |
401 | Credenciais erradas no POST /external/v1/auth, ou accessToken ausente ou vencido. |
402 | Assinatura da empresa suspensa: criações e atualizações são recusadas (code = SUBSCRIPTION_SUSPENDED); as leituras continuam funcionando. |
403 | Recurso 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). |
404 | Registro inexistente numa atualização ou numa regra de negócio que procura outro registro. |
409 / 422 | Conflito com o estado de outro registro (usados, por exemplo, nos pedidos de contratação). |
429 | Limite de requisições excedido. Veja Rate limits. |
500 | Erro inesperado. Tente de novo em alguns segundos; se persistir, abra um chamado com o X-Request-ID da resposta. |
502 | Um serviço de terceiro usado pela operação falhou. |
Erros comuns
Autenticação (401 e 403)
friendlyMessage ou code | Causa | O 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 chave | accessToken vencido ou ausente. | Autentique de novo com POST /external/v1/auth. |
code = COMPANY_SESSION_EXPIRED | A 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)
friendlyMessage | Causa | O 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)
friendlyMessage | Causa | O 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
- Verifique o
statusantes de ler o corpo. - Ao receber
401ouCOMPANY_SESSION_EXPIRED, autentique de novo e repita a requisição uma vez. - Ao receber
429, espere e tente de novo (veja Rate limits). - Registre
status,path,friendlyMessagee oX-Request-IDpara investigar depois. - 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.