Mensajes de error comunes
Cuando una solicitud falla, Bird devuelve un error estructurado con un código legible por máquina, un mensaje, un enlace a la documentación y un ID de solicitud. Usa el código en la lógica de tu programa. Si necesitas soporte, selecciona Feedback > Contact us e incluye el ID de solicitud. Para el catálogo completo, consulta la referencia de errores de API.
Errores de validación
Significan que Bird entendió tu solicitud, pero algo en ella no es aceptable. El error indica el campo o la condición específica que falló.
Todos los destinatarios suprimidos
Qué significa: todos los destinatarios de tu envío están en tu lista de supresión, así que no quedó nada por entregar y el envío fue rechazado.
Causa probable: estás enviando a direcciones que anteriormente tuvieron rebote permanente, generaron una queja o se dieron de baja, lo cual suele indicar que estás reenviando a una lista antigua o sin depurar. Si solo algunos destinatarios están suprimidos, el envío se procesa para el resto y los suprimidos aparecen como rechazados; este error solo aparece cuando son todos.
La solución: revisa qué direcciones están suprimidas y por qué, y elimínalas de tu propia lista. ¿Por qué se rechazó mi correo? explica cómo aparecen los rechazos por supresión, y la guía de supresiones cubre la gestión de la lista.
Destinatario de onboarding no permitido
Qué significa: estás enviando desde el dominio compartido de onboarding de Bird a alguien que no es un miembro verificado de tu espacio de trabajo.
Causa probable: el dominio compartido solo entrega a miembros verificados del espacio de trabajo y a direcciones de prueba del sandbox.
La solución: para enviar correo a destinatarios reales, verifica tu propio dominio de envío, lo que elimina la restricción por completo. Consulta Envío desde el dominio compartido para conocer las limitaciones y cómo superarlas.
Campo faltante o inválido
Qué significa: falta un campo obligatorio, un valor es inválido o la solicitud combina campos incompatibles.
Causa probable: la solicitud no coincide con el esquema de la operación o combina campos incompatibles. Los detalles del error identifican cada campo que falló.
La solución: lee los detalles del error y corrige los campos indicados.
Errores de limitación de solicitudes
Qué significa: la solicitud excedió un límite de operación, de cuenta o de envío.
Causa probable: una ráfaga excedió un límite de solicitudes de API, o un envío excedió una cuota como el límite de destinatarios del dominio compartido de onboarding.
La solución: sigue la remediación del error y el valor de Retry-After cuando esté presente. Reintenta los límites transitorios con retroceso exponencial. Para el límite diario de onboarding, espera al reinicio del día UTC o verifica tu propio dominio de envío. La etiqueta de salud de correo throttled es diagnóstica y no causa un error de limitación de solicitudes API.
Errores de autenticación
Qué significa: Bird no pudo aceptar tus credenciales.
Causa probable: una de tres situaciones, en orden aproximado de frecuencia:
- Clave API incorrecta, expirada o revocada: la clave está mal escrita, truncada, expirada o ya no está activa. El secreto solo se muestra cuando la clave se crea o se rota.
- Clave usada contra la región equivocada: las claves de API son regionales y solo funcionan contra los servidores de su propia región. Si tu clave se creó en una región y tu código llama a otra, la autenticación falla. El prefijo de la clave indica a qué región pertenece.
- Clave faltante: la solicitud no incluyó credenciales, a menudo porque una variable de entorno está vacía en el entorno donde falla.
La solución: confirma que la clave existe y está activa en tu dashboard, que tu código la está enviando y que estás llamando a la dirección regional que corresponde a la clave. Si tienes dudas, crea una clave nueva y reemplázala.
Dominio no verificado
Qué significa: el dominio de envío no completó la verificación, por lo que Bird no puede enviar desde él.
Causa probable: los registros DNS faltan, aún se están propagando o son incorrectos, o los registros cambiaron después de la verificación. Consulta la lista de verificación de dominios para los tiempos esperados.
La solución: abre la página del dominio en el dashboard para identificar el registro pendiente. Usa la lista de verificación de dominios para corregirlo. Mientras el DNS se propaga, usa el dominio compartido de onboarding para envíos de prueba.
Cómo leer cualquier error que encuentres
Compara usando el código de error legible por máquina, porque los mensajes legibles pueden cambiar. Registra el ID de solicitud. Si necesitas soporte, selecciona Feedback > Contact us e inclúyelo. Sigue el enlace a la documentación para la remediación específica del error.
Próximos pasos
- Referencia de errores de API (el catálogo completo: cada tipo de error, código y estado)
- ¿Por qué se rechazó mi correo?: las razones detrás de los rechazos por destinatario
- ¿Por qué la salud de correo muestra Throttled?: la etiqueta diagnóstica de salud y las señales detrás de ella
- Envío desde el dominio compartido: las limitaciones de destinatarios y límite diario del dominio de onboarding
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaWhat happens when someone opts outComprender el conceptoWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Explorar la funcionalidadEmail opt-outsSeguir la ruta de aprendizajeOperate messaging reliably
Obtener un resumen de implementación