API en Tiempo Real: errores, límites y respuestas de la API
Guía técnica para interpretar errores, límites de uso y respuestas de la API en Tiempo Real sin afectar formularios ni integraciones.
Priscila G.
Última actualización hace 9 días
La API en tiempo real de SafetyMails está diseñada para funcionar de forma estable incluso en entornos de gran volumen. Las preguntas más frecuentes relacionadas con la API no se refieren a la validación del correo electrónico en sí, sino a los errores de retorno, los límites de uso y el comportamiento esperado de la API en situaciones específicas.
Este documento centraliza esta información y explica cómo interpretar correctamente cada retorno, evitando la confusión entre error técnico, límite del plan y funcionamiento normal del sistema.
Este documento centraliza esta información y explica cómo interpretar correctamente cada retorno, evitando la confusión entre error técnico, límite del plan y funcionamiento normal del sistema.
Cómo tratamos cada solicitud de la API en tiempo real
Antes de realizar cualquier verificación de correo electrónico, cada solicitud recibida por la API en tiempo real pasa por una etapa de validaciones técnicas y de conformidad. En esta etapa, el sistema evalúa si la solicitud es apta para ser procesada, teniendo en cuenta criterios como la autenticación, el origen de la llamada, los límites de uso y la disponibilidad de créditos.
Solo después de este análisis preliminar, la solicitud se envía a la etapa de verificación del correo electrónico. Si alguna de estas validaciones iniciales falla, la API devuelve inmediatamente un error técnico, sin ejecutar la verificación.
Este flujo garantiza la estabilidad, la protección contra el uso indebido y la previsibilidad en el comportamiento de la API, sin bloquear formularios ni interrumpir las integraciones.
Solo después de este análisis preliminar, la solicitud se envía a la etapa de verificación del correo electrónico. Si alguna de estas validaciones iniciales falla, la API devuelve inmediatamente un error técnico, sin ejecutar la verificación.
Este flujo garantiza la estabilidad, la protección contra el uso indebido y la previsibilidad en el comportamiento de la API, sin bloquear formularios ni interrumpir las integraciones.
Errores de retorno de la API (Success = false)
Los mensajes siguientes solo se muestran cuando el campo Success devuelve false en la respuesta de la API. En estos casos, la consulta no se ha realizado correctamente y el campo Msg indica el motivo del fallo.
Estos errores están relacionados con problemas de autenticación, parámetros incorrectos, origen de la API, falta de créditos o límites excedidos.
Ejemplo de respuesta con error A continuación se muestra un ejemplo de respuesta de la API cuando se produce un error técnico y el campo Success devuelve el valor false:
Estos errores están relacionados con problemas de autenticación, parámetros incorrectos, origen de la API, falta de créditos o límites excedidos.
Ejemplo de respuesta con error A continuación se muestra un ejemplo de respuesta de la API cuando se produce un error técnico y el campo Success devuelve el valor false:
{
"Success": false,
"Email": "testeemail@safetymails.com",
"Referer": "www.safetymails.com",
"Status": "PENDENTE",
"Advice": "Unknown",
"Msg": "Referer inválido"
}
"Success": false,
"Email": "testeemail@safetymails.com",
"Referer": "www.safetymails.com",
"Status": "PENDENTE",
"Advice": "Unknown",
"Msg": "Referer inválido"
}
En este escenario, la solicitud se interrumpió en la etapa de validación preliminar (origen no válido) y no se realizó ninguna verificación de correo electrónico.
| HTTP Code | Erro | Descrição |
| 400 | Parámetros no válidos | Parámetros o claves de acceso incorrectos o inexistentes en la solicitud. |
| 401 | Clave API no válida | La clave de acceso introducida no es válida o no existe. |
| 402 | Sin créditos para realizar la investigación | La cuenta no tiene suficientes créditos para realizar la consulta. |
| 403 | Origen diferente al registrado | La solicitud se está realizando desde una fuente diferente a la registrada en la cuenta. |
| 406 | Ticket de origen inválido o inactivo | El origen de la API está inactivo y debe activarse correctamente en el panel. |
| 429 | Límite de consultas superado | Se ha superado el límite de consultas por minuto, hora o día. |
Quando Success = false, nenhuma validação é executada
Sandbox x Producción
Sandbox
• Entorno destinado exclusivamente a pruebas.
• No refleja los límites reales del plan contratado.
• Puede devolver respuestas simuladas.
• No debe utilizarse en formularios activos.
Producción
• Entorno real de uso.
• Consume créditos.
• Aplica límites por minuto, hora y día.
• Refleja exactamente el comportamiento descrito en este documento.
Los errores observados en producción no deben compararse con las pruebas realizadas únicamente en el sandbox.
• Entorno destinado exclusivamente a pruebas.
• No refleja los límites reales del plan contratado.
• Puede devolver respuestas simuladas.
• No debe utilizarse en formularios activos.
Producción
• Entorno real de uso.
• Consume créditos.
• Aplica límites por minuto, hora y día.
• Refleja exactamente el comportamiento descrito en este documento.
Los errores observados en producción no deben compararse con las pruebas realizadas únicamente en el sandbox.
Límites de uso de la API
Cada plan tiene límites específicos de:
• solicitudes por minuto
• solicitudes por hora
• solicitudes diarias
Estos límites varían según el plan contratado y forman parte de las reglas de uso justo de la API. Los valores oficiales se describen en los Términos de uso de la plataforma: https://www.safetymails.com/terms-of-use/
• solicitudes por minuto
• solicitudes por hora
• solicitudes diarias
Estos límites varían según el plan contratado y forman parte de las reglas de uso justo de la API. Los valores oficiales se describen en los Términos de uso de la plataforma: https://www.safetymails.com/terms-of-use/
¿Qué sucede cuando se supera el límite?
Cuando el uso de la API supera el límite permitido por el plan:
• los formularios no se bloquean
• la API sigue respondiendo
• las solicitudes que han superado el límite quedan con el estado PENDIENTE
• el comportamiento se muestra en el gráfico de consumo diario de la API
Este mecanismo existe para preservar la experiencia del usuario final, evitar fallos en el front-end y señalar un uso que no se ajusta al plan contratado.
• los formularios no se bloquean
• la API sigue respondiendo
• las solicitudes que han superado el límite quedan con el estado PENDIENTE
• el comportamiento se muestra en el gráfico de consumo diario de la API
Este mecanismo existe para preservar la experiencia del usuario final, evitar fallos en el front-end y señalar un uso que no se ajusta al plan contratado.
Los datos de la API no aparecen
Cuando los datos de la API no aparecen como se espera, normalmente se debe a:
• uso incorrecto del entorno (sandbox x producción)
• autenticación no válida
• error de interpretación de la respuesta
• solicitudes afectadas por un límite momentáneo o por la expiración de la API debido a la falta de confirmación del pago de la suscripción mensual o anual (la cancelación se produce tras 3 días sin confirmación del pago)
Antes de escalar, es importante validar el entorno utilizado, la clave API y los registros de integración.
• uso incorrecto del entorno (sandbox x producción)
• autenticación no válida
• error de interpretación de la respuesta
• solicitudes afectadas por un límite momentáneo o por la expiración de la API debido a la falta de confirmación del pago de la suscripción mensual o anual (la cancelación se produce tras 3 días sin confirmación del pago)
Antes de escalar, es importante validar el entorno utilizado, la clave API y los registros de integración.
Límites visibles en el gráfico de consumo (color lila)
Este escenario no representa un error técnico de la API.
Cuando el uso de la API excede los límites del plan:
• el consumo aparece en el gráfico diario marcado en color lila
• las solicitudes asociadas quedan con el estado PENDIENTE
• no hay bloqueo de formularios
• no hay interrupción de la API
Este comportamiento existe para señalar un uso no conforme sin afectar al funcionamiento.
Cuando el uso de la API excede los límites del plan:
• el consumo aparece en el gráfico diario marcado en color lila
• las solicitudes asociadas quedan con el estado PENDIENTE
• no hay bloqueo de formularios
• no hay interrupción de la API
Este comportamiento existe para señalar un uso no conforme sin afectar al funcionamiento.
Cuándo escalar al soporte técnico
Este documento debe ser el primer punto de consulta.
Si, tras leer este artículo, persisten las dudas, el servicio de asistencia técnica está disponible para ayudarle en horario comercial.
• El error persiste tras seguir esta guía.
• Hay indicios de un error específico de implementación.
• El comportamiento no se corresponde con el descrito en este documento.
En la mayoría de los casos, los ajustes en la lógica de integración, el volumen de solicitudes o el plan contratado resuelven el problema.
Si, tras leer este artículo, persisten las dudas, el servicio de asistencia técnica está disponible para ayudarle en horario comercial.
• El error persiste tras seguir esta guía.
• Hay indicios de un error específico de implementación.
• El comportamiento no se corresponde con el descrito en este documento.
En la mayoría de los casos, los ajustes en la lógica de integración, el volumen de solicitudes o el plan contratado resuelven el problema.