Erros

Formato das respostas de erro, códigos por situação e o que fazer em cada um.

Formato

Toda resposta de erro é JSON com success: false e um texto curto em error. Quando a causa é identificável por máquina, vem também um code. Alguns erros trazem correlationId, que é o que o suporte pede para localizar a requisição.

{
  "success": false,
  "code": "ACCOUNT_API_SCOPE_REQUIRED",
  "error": "A chave nao tem o escopo messages:send"
}

Trate o code como contrato e o error como texto para humanos: o texto pode mudar, o código não muda sem aviso no changelog.

Por status HTTP

Status	Significa	O que fazer
`400`	Pedido malformado: campo faltando, telefone fora do E.164, tipo não suportado	Corrija o pedido conforme a referência. Não repita igual.
`401`	Credencial ausente, desconhecida, revogada ou vencida	Confira o cabeçalho e a chave. Se foi revogada, crie outra.
`403`	Credencial válida, mas sem direito a esta operação	Veja o `code`: escopo, tipo de credencial ou linha errada.
`404`	Recurso não existe nesta conta	Confira o `instanceId`. Nunca tente identificadores de outra conta.
`409`	Conflito de estado ou chave natural repetida	Consulte o recurso existente antes de repetir.
`429`	Muitas tentativas inválidas da mesma origem	Espere e corrija a credencial. Não insista em loop.
`5xx`	Falha do lado do Nexus	Repita com a mesma `Idempotency-Key` após alguns segundos; se persistir, acione o suporte com o `correlationId`.

Códigos de autorização

`code`	Status	Situação
`ACCOUNT_API_KEY_INVALID`	`401`	Chave da conta desconhecida, revogada, inativa ou vencida
`ACCOUNT_API_ROUTE_NOT_ALLOWED`	`403`	A operação não aceita chave da conta; use sessão ou outra credencial
`ACCOUNT_API_SCOPE_REQUIRED`	`403`	A chave não tem o escopo que a operação exige
`ACCOUNT_API_UNAVAILABLE`	`503`	O servidor não conseguiu validar chaves da conta neste momento; repita em instantes
`USER_AUTH_REQUIRED`	`403`	A operação exige sessão do painel; chaves não servem
`INSTANCE_API_KEY_SCOPE_VIOLATION`	`403`	A chave da linha tentou operar outra linha
`INSTANCE_API_KEY_SCOPE_MISMATCH`	`403`	A chave da linha tentou uma operação fora do alcance dela
`ACCOUNT_API_KEYS_ROLE_REQUIRED`	`403`	Gerenciar chaves exige dono ou administrador
`ACCOUNT_API_KEYS_IMPERSONATION_BLOCKED`	`403`	Operador da plataforma dentro da conta de um cliente não cria chave; só o próprio dono ou administrador

Códigos de gerenciamento de chaves

`code`	Status	Situação
`account_api_key_label_invalid`	`400`	Nome vazio ou com mais de 80 caracteres
`account_api_key_scopes_required`	`400`	Nenhum escopo informado
`account_api_key_scope_unknown`	`400`	Escopo fora do catálogo
`account_api_key_expiry_invalid`	`400`	Validade no passado ou em formato inválido
`account_api_key_limit`	`409`	A conta já tem 20 chaves ativas
`account_api_key_not_found`	`404`	Chave não existe nesta conta

Como tratar erros numa integração

400 e 404 são erros do pedido: logue, corrija e não repita automaticamente.
401 e 403 são erros de credencial ou permissão: pare a integração e avise quem administra. Repetir só acumula 429.
409 pede leitura antes de ação: consulte o recurso e decida.
5xx e timeout pedem repetição com a mesma Idempotency-Key, com intervalo crescente e teto de tentativas.
Guarde o correlationId quando vier. É o que encurta o suporte.

Evidência mínima para o suporte

Horário, ambiente, operação (operationId da referência), correlationId, status e code. Remova credenciais, telefones, conteúdo de mensagens e dados de clientes antes de enviar.