Ajuda
Erros e resolução
O que corrigir e quando repetir
X-Request-Id. Guarda este valor quando ocorrer um erro e envia-o ao suporte; ele permite localizar o pedido sem partilhar a API key, o token ou o conteúdo da mensagem. Para investigar uma falha, guarda X-Request-Id e os campos reservation_id ou message_id devolvidos pela operação. Num replay idempotente, X-Original-Request-Id identifica o pedido original quando disponível. Podes enviar um UUID como identificador do pedido. Outros formatos são substituídos por um UUID gerado. Nunca envies credenciais, códigos, telefones ou conteúdo de mensagens ao suporte.Falhas inesperadas devolvem uma mensagem genérica e INTERNAL_ERROR. JSON inválido usa INVALID_REQUEST (400), pedidos demasiado grandes REQUEST_TOO_LARGE (413), codificação não suportada UNSUPPORTED_ENCODING (415) e rotas inexistentes NOT_FOUND (404). Usa o estado HTTP e o code na integração; o texto do erro pode mudar. A expiração invalida a credencial; não apaga o histórico da operação nem devolve automaticamente o custo de um SMS. Uma resposta 202 de reconciliação exige revisão do resultado: não repitas o envio automaticamente.
Códigos de erro
VALIDATION_ERROR
Pedido inválido
Parâmetros inválidos ou em falta. Revê corpo, formato e conteúdo.
Consumo
Não
Repetir
Depois de corrigir
UNAUTHORIZED
Não autenticado
API Key inválida, revogada ou em falta. Confirma a chave e o header.
Consumo
Não
Repetir
Sim
INSUFFICIENT_BALANCE
Saldo insuficiente
A conta não tem créditos SMS suficientes. Recarrega SMS e OTP.
Consumo
Não
Repetir
Depois da recarga
EMAIL_QUOTA_EXHAUSTED
Volume de email esgotado
O ciclo do Kamba Email não tem volume disponível. Ativa outro pacote de email.
Consumo
Não
Repetir
Depois da recarga
NOT_FOUND
Não encontrado
O recurso não existe ou não pertence à conta. Confirma o identificador.
Consumo
Não
Repetir
Não
EMAIL_SUPPRESSED
Destinatário suprimido
Bounce permanente ou reclamação bloqueou o endereço. Não forces um novo envio.
Consumo
Não
Repetir
Não
RATE_LIMITED
Limite atingido
A proteção de frequência recusou temporariamente o pedido. Respeita Retry-After quando existir.
Consumo
Não
Repetir
Após o intervalo
INTERNAL_ERROR
Erro interno
A plataforma não concluiu a operação. Guarda X-Request-Id e contacta o suporte.
Consumo
Confirmar histórico
Repetir
Com idempotência