Errores de entrega de SMS
Un SMS no entregado tiene un estado de entrega y un error que explica el resultado. Usa esta referencia para interpretar el motivo de fallo y el código numérico del proveedor asociados a un mensaje.
Los errores de solicitud, como un payload de envío no válido, usan el catálogo de errores de API. Los códigos de esta página describen mensajes que fueron aceptados y luego fallaron o fueron rechazados.
Leer el error
Abre un mensaje en el registro de SMS y selecciona Detalles. Error muestra la descripción y el motivo de fallo normalizado. Carrier error code muestra el código numérico del proveedor cuando se proporcionó uno.
A través de la API, consulta GET /v1/sms/messages/{message_id}. Su last_error contiene:
| Campo | Significado |
|---|---|
code | Motivo de fallo normalizado de Bird, como unreachable o unknown |
description | La explicación reportada en palabras |
carrier_error_code | El código sin procesar del proveedor, cuando se proporcionó |
occurred_at | Cuándo ocurrió el fallo |
Los eventos de webhook de fallo y los eventos de línea de tiempo del mensaje contienen los mismos campos en error.
El nombre de campo carrier_error_code también abarca códigos emitidos por el proveedor de envío de Bird, incluidos los bloqueos de protección contra fraude. Un código ausente significa que el proveedor no proporcionó ninguno o que el mensaje fue rechazado antes del envío.
Razones de fallo normalizadas
Estas son las razones de fallo definidas por el mensaje API. Los acuses de recibo del proveedor pueden contener un código numérico más específico del que refleja la razón normalizada. Por ejemplo, un mensaje con code: unknown puede llevar igualmente un carrier_error_code reconocido.
| Razón | Significado |
|---|---|
invalid_destination | El número no está asignado o no es válido |
unreachable | El terminal está apagado o fuera de cobertura |
blocked_by_carrier | El operador receptor filtró el mensaje |
blocked_by_fraud_protection | La protección antifraude de Bird bloqueó una sospecha de inflado de tráfico (SMS pumping) |
blocked_by_recipient | El dispositivo del destinatario bloqueó al remitente |
landline_unreachable | La línea fija no acepta SMS |
content_rejected | El operador rechazó el contenido |
sender_unregistered | El remitente no tiene el registro requerido |
recipient_opted_out | El destinatario está en una lista de supresión |
provider_unavailable | El proveedor o la red no estaba disponible |
insufficient_balance | El saldo del espacio de trabajo no pudo cubrir el envío |
unknown | El fallo no pudo clasificarse |
Es un conjunto abierto: acepta valores desconocidos y conserva la descripción y el código en bruto para investigar. Una causa temporal igualmente finaliza este intento de mensaje; no garantiza un reenvío automático.
Códigos de error del proveedor
Busca la cadena numérica devuelta en carrier_error_code. Estos códigos pertenecen al proveedor de envío de SMS de Bird; un proveedor distinto puede asignar otros significados a los mismos números.
| Código | Significado |
|---|---|
0 | Sin error |
1 | Suscriptor desconocido |
2 | Estación base desconocida |
3 | Conmutador móvil desconocido |
5 | Suscriptor no identificado |
7 | El terminal no puede conectarse |
8 | Itinerancia prohibida |
9 | Autenticación del suscriptor fallida |
10 | Portadora SMS no aprovisionada |
11 | Servicio SMS no aprovisionado |
12 | Terminal en lista negra |
13 | Servicio SMS bloqueado |
21 | SMS no compatible |
26 | Traspaso de red fallido |
27 | Suscriptor no disponible |
28 | Fuera de cobertura |
29 | Terminal apagado |
30 | Fallo en la central móvil |
31 | Suscriptor ocupado |
32 | Fallo en la entrega de SMS |
33 | Almacenamiento de mensajes pendientes lleno |
34 | Fallo del sistema de red |
35 | Datos obligatorios ausentes |
36 | Valor inesperado en un campo del mensaje |
39 | Número de enrutamiento en itinerancia no disponible |
40 | Memoria de red agotada |
71 | Alfabeto no compatible |
72 | USSD ocupado |
100 | Saldo de envío insuficiente |
101 | Saldo del suscriptor insuficiente |
103 | El suscriptor canceló la suscripción |
104 | Remitente no registrado |
105 | Contenido no registrado |
106 | Volumen de campaña excedido |
107 | Rendimiento de campaña excedido |
110 | El operador filtró el mensaje |
130 | SurgeGuard detectó bombeo de tráfico |
131 | SurgeGuard bloqueó un destino sospechoso de bombeo |
El código 0 se omite de carrier_error_code en las lecturas de mensajes y eventos de Bird. Un código desconocido debe permanecer disponible en tus registros cuando contactes con soporte.
Bloqueos de protección contra fraude
SurgeGuard es la protección contra fraude de SMS de Bird.
Los mensajes bloqueados por la protección contra fraude tienen el motivo de fallo blocked_by_fraud_protection y la descripción "Blocked by fraud protection: suspected SMS pumping." El estado de entrega permanece como failed, rejected o expired, según el informe del proveedor. El mismo motivo y la misma descripción aparecen en los detalles del mensaje, los eventos de línea de tiempo y los webhooks de fallo. El código sin procesar del proveedor sigue disponible en carrier_error_code cuando se proporciona.
En el registro de SMS, filtra Failure reason por Blocked by fraud protection para encontrar estos mensajes.
Los registros más antiguos pueden seguir mostrando unknown y generic_delivery_failure. Estas etiquetas por sí solas no identifican un bloqueo por protección contra fraude. Busca su carrier_error_code en Códigos de error del proveedor para identificar la causa. Si el código falta o no lo reconoces, contacta con soporte indicando el ID del espacio de trabajo, el ID del mensaje, la marca de tiempo y el código del proveedor, si se proporcionó.
Al investigar un OTP bloqueado, correlaciona el SMS con la cuenta o la solicitud de verificación que lo originó. Evita reenviar automáticamente o cambiar de ruta para eludir el bloqueo. Si sospechas que una solicitud legítima fue bloqueada, contacta con soporte indicando el ID del espacio de trabajo, el ID del mensaje, la marca de tiempo y el código del proveedor.
Próximos pasos
- Registro de SMS: inspecciona un mensaje y su historial de entrega.
- Eventos de SMS: consume webhooks de entrega y de fallo.
- Métricas de SMS: revisa los resultados agregados de fallos.
- Errores de API de SMS: interpreta los errores devueltos por una solicitud API.
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.