Erros de entrega SMS

Uma mensagem SMS malsucedida tem um status de entrega e um erro que explica o resultado. Use esta referência para interpretar o motivo de falha e o código numérico do provedor reportados com a mensagem.

Erros de solicitação, como um payload de envio inválido, usam o catálogo de erros API. Os códigos nesta página descrevem mensagens que foram aceitas e depois falharam ou foram rejeitadas.

Lendo o erro

Abra uma mensagem no log SMS e selecione Detalhes. Erro mostra a descrição e o motivo de falha normalizado. Código de erro da operadora mostra o código numérico do provedor quando fornecido.

Pela API, leia GET /v1/sms/messages/{message_id}. O last_error contém:

Eventos de webhook de falha e eventos de linha do tempo da mensagem contêm os mesmos campos em error.

O nome de campo carrier_error_code também abrange códigos emitidos pelo provedor de envio da Bird, incluindo bloqueios de proteção contra fraude. Um código ausente significa que o provedor não forneceu nenhum ou que a mensagem foi recusada antes do envio.

Motivos de falha normalizados

Estes são os motivos de falha definidos pelo API da mensagem. Os recibos do provedor podem conter um código numérico mais específico do que o motivo normalizado reflete. Por exemplo, uma mensagem com code: unknown ainda pode conter um carrier_error_code reconhecido.

Este é um conjunto aberto: aceite valores desconhecidos e mantenha a descrição e o código bruto para investigação. Uma causa temporária ainda encerra esta tentativa de envio da mensagem; ela não garante reenvio automático.

Códigos de erro do provedor

Consulte a string numérica retornada em carrier_error_code. Esses códigos pertencem ao provedor de envio SMS da Bird; um provedor diferente pode atribuir outros significados aos mesmos números.

O código 0 é omitido de carrier_error_code nas leituras de mensagens e eventos de Bird. Um código desconhecido deve permanecer disponível nos seus registros quando você entrar em contato com o suporte.

Bloqueios de proteção contra fraude

SurgeGuard é a proteção contra fraude de SMS da Bird.

Mensagens bloqueadas pela proteção contra fraude têm o motivo de falha blocked_by_fraud_protection e a descrição "Blocked by fraud protection: suspected SMS pumping." O status de entrega permanece failed, rejected ou expired, conforme o relatório do provedor. O mesmo motivo e descrição aparecem nos detalhes da mensagem, nos eventos de linha do tempo e nos webhooks de falha. O código bruto do provedor permanece disponível em carrier_error_code quando fornecido.

No log de SMS, filtre Failure reason por Blocked by fraud protection para encontrar essas mensagens.

Registros mais antigos ainda podem exibir unknown e generic_delivery_failure. Esses rótulos sozinhos não identificam um bloqueio de proteção contra fraude. Consulte o carrier_error_code correspondente em Códigos de erro do provedor para identificar a causa. Se o código estiver ausente ou não for reconhecido, entre em contato com o suporte informando o ID do espaço de trabalho, o ID da mensagem, o timestamp e o código do provedor, se fornecido.

Ao investigar uma OTP bloqueada, correlacione o SMS com a conta ou solicitação de verificação que o originou. Evite reenviar automaticamente ou trocar de rota para contornar o bloqueio. Se você suspeitar que uma solicitação legítima foi bloqueada, entre em contato com o suporte informando o ID do espaço de trabalho, o ID da mensagem, o timestamp e o código do provedor.

Próximos passos

• Log de SMS: inspecione uma mensagem e seu histórico de entrega.
• Eventos de SMS: consuma webhooks de entrega e falha.
• Métricas de SMS: analise os resultados agregados de falha.
• Erros de API de SMS: interprete erros retornados por uma solicitação API.