Códigos de erro — Integration API

Erros do Endpoint de Token (POST /api/integration/auth/token)

O endpoint de token retorna erros no formato OAuth2 padrão:

{
  "error": "error_code",
  "error_description": "Human-readable description"
}

HTTP Status	Código OAuth2	Descrição	Como Resolver
`400`	`unsupported_grant_type`	O `grant_type` informado não é suportado	Usar `client_credentials` ou `password`
`400`	`invalid_request`	Parâmetros obrigatórios ausentes ou malformados	Verificar se `client_id` e `grant_type` estão presentes
`401`	`invalid_client`	Client ID ou client secret inválidos	Verificar credenciais do client OAuth2
`401`	`invalid_grant`	Credenciais de usuário inválidas (username/password)	Verificar email e senha do usuário
`401`	`unauthorized_client`	Client não tem permissão para o grant type solicitado	Verificar a configuração da API key no IAM

Endpoints autenticados retornam erros no formato padrão da API:

{
  "code": "string",
  "message": "string",
  "success": false
}

HTTP Status	Descrição	Causa Comum	Como Resolver
`401 Unauthorized`	Token JWT ausente ou inválido	Header `Authorization` não enviado ou token expirado	Obter um novo token via `POST /api/integration/auth/token`
`403 Forbidden`	Permissões insuficientes	Usuário não tem role necessária para acessar o recurso	Verificar as roles atribuídas à API key ou ao usuário no IAM
`403 Forbidden`	Cliente incorreto	Tentativa de acessar dados de outro customer	Verificar o header `X-Customer-Id` ou o claim `customer-id` no JWT
`400 Bad Request`	Violação de regra de domínio	Parâmetros inválidos ou regra de negócio não atendida	Verificar a mensagem de erro retornada no campo `message`
`400 Bad Request`	Erro de validação	Campo obrigatório ausente ou formato inválido	Verificar os campos enviados conforme a documentação
`500 Internal Server Error`	Erro interno	Falha inesperada no servidor	Entrar em contato com o suporte técnico

Erros de domínio retornam HTTP 400 com um código específico no campo code:

{
  "code": "DOMAIN_ERROR_CODE",
  "message": "Mensagem descritiva localizada",
  "success": false
}

O campo message é localizado de acordo com o header Accept-Language (suporta pt-BR e en-US).

Sempre verifique o campo success na resposta para determinar se a operação foi bem-sucedida
Trate tokens expirados automaticamente: ao receber 401, obtenha um novo token e repita a requisição
Não armazene tokens indefinidamente: respeite o expires_in retornado no token
Logue os códigos de erro para facilitar troubleshooting com a equipe de suporte