A resposta curta: na API de verificação, um código errado não é um erro: a conferência responde 200 com valid: false. Os erros HTTP querem dizer outra coisa: a chave (401, 403), o estado do código (409), os dados (422) ou um limite (429). Decida sempre pelo error.code e pelo details, nunca pelo texto da mensagem, que muda com a língua.
As respostas, uma a uma
| Resposta |
Quer dizer |
O que fazer |
| 201 |
Código criado e enviado (ou simulado, na Sandbox) |
Guarde o id |
| 200 com valid: true |
Código certo |
Continue |
| 200 com valid: false |
Código errado, expirado, falhado ou substituído |
Leia status e attempts_left |
| 401 |
Chave em falta, inválida, revogada ou fora de validade |
Confirme a chave ou crie outra |
| 403 |
A chave não tem a permissão (insufficient_scope), o IP não está na lista (ip_not_allowed) ou o SMS não está activo (sms_reseller_required) |
Corrija a chave ou active o SMS no Meu Interweb |
| 404 |
O id não existe ou não é da sua conta |
Confirme o id guardado |
| 409 |
A operação não se faz no estado actual; o motivo vem em details.reason |
Por exemplo, reenviar um código já verificado: peça um novo |
| 422 |
Dados inválidos (validation_failed), com o campo e o motivo em details |
Por exemplo, invalid_number: peça ao cliente para confirmar o número |
| 429 |
Demasiados pedidos: o limite da API, ou as regras de códigos que definiu na conta |
Espere os segundos de Retry-After |
| 500, 502, 503 |
Falha do nosso lado, ou API desligada |
Tente mais tarde; guarde o correlation_id |
O formato de um erro
Todos os erros têm a mesma forma: error.code (estável, em inglês, para o seu programa), error.message (para pessoas, na língua de Accept-Language), error.correlation_id (igual ao cabeçalho X-Correlation-ID) e error.details.
Repetir ou não repetir
| 1 |
Vale a pena repetir, com espera: 429, 500, 502 e 503. Se o 429 voltar, aumente a espera.
|
|
| 2 |
Não vale a pena repetir sem mudar nada: todos os outros.
|
|
| 3 |
No envio, repita com a mesma Idempotency-Key. A mesma chave com o mesmo corpo devolve a resposta guardada e não envia outro SMS; com outro corpo, ou com o primeiro pedido ainda em curso, dá 409 (idempotency_conflict). A chave fica reservada durante 24 horas.
|
|
| 4 |
Na conferência, veja o estado antes de repetir com GET /v1/sms/otp/{id}: cada conferência com o código errado gasta uma tentativa.
|
|
|
Não mostre ao cliente o texto técnico do erro. Traduza para uma frase simples: «O número não parece válido», «Pediu demasiados códigos, tente daqui a pouco». Os códigos de erro gerais da API estão também em erros e estados das mensagens na API de SMS.
|
|
Para pedir ajuda, junte o correlation_id, a hora e a operação. Nunca envie a chave: o suporte não precisa dela.
|
|
Quer a referência completa de cada operação de verificação? Veja a página da API.
Ver a página da API
|
PRODUTO RECOMENDADO Hospedagem de sites com cPanel Domínio e SSL incluídos, cópias diárias e o painel que já conhece. desde 321,75 MT/mês (plano de 3 anos, com cupão) Ver planos |
Português
English
