Erros e recuperação

Formato da resposta#

{
  "type": "https://aut2fa.com/docs/errors#invalid_recipient",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "invalid_recipient",
  "detail": "\"to\" must be a phone number in international format (+5531999999999) or an e-mail address"
}

Não compare a mensagem em detail. Em 429, leia também Retry-After.

Uma verificação com valid: false e HTTP 200 é um resultado de verificação; não usa este envelope.

missing_credentials#

HTTP 401

A requisição não trouxe um Bearer token.

Envie Authorization: Bearer SUA_CHAVE a partir do seu servidor.

invalid_api_key#

HTTP 401

A chave não é válida ou foi revogada.

Confira a variável de ambiente e a aplicação no painel. Substitua a credencial se ela foi revogada.

invalid_recipient#

HTTP 422

O destinatário não passou pela validação de formato.

Use um telefone válido com + e código do país, como +5531999999999. E-mail válido ainda não habilita entrega por e-mail.

channel_unavailable#

HTTP 422

O destinatário é um e-mail, mas a entrega pública por e-mail ainda não está disponível.

Informe um telefone válido. O fluxo público atual entrega por WhatsApp; configurar SMTP no painel não altera essa disponibilidade.

invalid_code#

HTTP 422

O código próprio no pedido de envio não tem de 4 a 10 dígitos.

Envie code como string de dígitos, preservando zeros iniciais, ou omita o campo para gerar um código. Esse erro pertence à criação: um código incorreto em verify retorna HTTP 200 com valid: false.

invalid_locale#

HTTP 422

O idioma informado não é suportado.

Use pt-BR ou en, ou omita locale para usar o idioma da conta.

invalid_idempotency_key#

HTTP 422

A chave de idempotência ultrapassou 255 bytes após trim.

Use uma chave ASCII de até 255 bytes, como um UUID. O limite é de bytes, não de caracteres Unicode.

idempotency_key_reused#

HTTP 409

A chave já foi usada nessa aplicação com outro corpo de requisição.

Para retentar o mesmo pedido, recupere os bytes originais do corpo. Para um novo pedido, gere outra chave. Espaços e ordem dos campos também alteram o hash.

send_not_found#

HTTP 404

O ID não existe na conta autenticada.

Use o ID retornado na criação e a chave da conta correta. Recupere o ID da sessão do servidor, em vez de aceitar um ID arbitrário da interface.

insufficient_credits#

HTTP 402

A conta não tem cota grátis nem crédito disponível para um envio live.

Confira o saldo no painel e regularize-o antes de retentar. O modo test não consome cota nem crédito.

rate_limited#

HTTP 429

Um limite de criação por conta, aplicação ou destinatário foi atingido.

Aguarde os segundos informados no cabeçalho Retry-After. Preserve a chave e o corpo nas retentativas do mesmo pedido.

invalid_json#

HTTP 422

O corpo não pôde ser lido como o JSON esperado, ou excedeu o limite de 64 KiB.

Envie um objeto JSON com os tipos corretos e Content-Type: application/json. Corrija o corpo antes de retentar.

internal_error#

HTTP 500

A API não conseguiu devolver o resultado por um erro interno.

Na criação do envio, retente com intervalo crescente e limite de tentativas, preservando a chave de idempotência e o corpo. Em verify, evite retentativas automáticas: o código pode já ter sido consumido. Consulte o status para diagnosticar, mas só retome a autenticação se seu próprio backend já registrou valid: true para essa sessão. Se o resultado continuar indeterminado, crie outro desafio. Veja verificação de uso único e recuperação.