Referencia completa de respuestas de error de la Agent API y cómo manejarlas.
Códigos de estado HTTP
| Estado | Significado | Acción |
|---|---|---|
| 200 | Éxito | Procesar los datos de la respuesta |
| 400 | Petición incorrecta | Revisar formato y parámetros |
| 401 | No autorizado | Comprobar que la clave API sea válida y esté incluida |
| 404 | No encontrado | Comprobar que exista el ID del recurso |
| 429 | Límite de tasa | Esperar antes de reintentar |
| 500 | Error del servidor | Reintentar más tarde o contactar con soporte |
Errores de registro
Formularioato de correo inválido
Estado: 400
Respuesta:
{
"error": "Invalid email format"
}
Causa: El correo no coincide con un patrón válido
Solución: Validar el formato del correo antes de enviar
Correo desechable
Estado: 400
Respuesta:
{
"error": "Disposable email addresses are not allowed"
}
Causa: El correo es de un dominio desechable conocido
Solución: Usar una dirección de correo permanente
Límite de tasa superado (por correo)
Estado: 429
Respuesta:
{
"error": "Rate limit exceeded: max 1 request per email per 24 hours"
}
Causa: El mismo correo se usó en las últimas 24 horas
Solución: Esperar 24 horas o usar otro correo
Límite de tasa superado (por IP)
Estado: 429
Respuesta:
{
"error": "Rate limit exceeded: too many requests from this IP"
}
Causa: Demasiadas peticiones desde la misma IP
Solución: Esperar antes de reintentar
Límite de tasa superado (global)
Estado: 429
Respuesta:
{
"error": "Service temporarily unavailable, please try again later"
}
Causa: Se alcanzó el límite de tasa del sistema
Solución: Reintentar tras un retraso
Campo obligatorio faltante
Estado: 400
Respuesta:
{
"error": "operator_email is required"
}
Causa: Falta un campo obligatorio en la petición
Solución: Incluir todos los campos obligatorios
Errores de comprobación de estado
Registro no encontrado
Estado: 404
Respuesta:
{
"error": "Registration not found"
}
Causa: registration_id inválido o inexistente
Solución: Comprobar que registration_id sea correcto
Token caducado
Estado: 200 (pero el status es "expired")
Respuesta:
{
"status": "expired",
"message": "Registration token has expired"
}
Causa: El operador no aprobó en 24 horas
Solución: Crear un nuevo registro
Registro rechazado
Estado: 200 (pero el status es "rejected")
Respuesta:
{
"status": "rejected",
"message": "Registration was declined by operator"
}
Causa: El operador hizo clic en "Decline"
Solución: Contactar con el operador o probar otro correo
Errores de la API de formularios
No autorizado (falta clave API)
Estado: 401
Respuesta:
{
"error": "Unauthorized"
}
Causa: Falta o es inválida la cabecera Authorization
Solución: Incluir cabecera Authorization: Bearer sr_live_xxx
Clave API inválida
Estado: 401
Respuesta:
{
"error": "Unauthorized"
}
Causa: La clave no existe, ha caducado o está inactiva
Solución:
- Comprobar que la clave sea correcta
- Verificar que no haya caducado
- Comprobar si fue revocada
Formularioulario no encontrado
Estado: 404
Respuesta:
{
"error": "Formulario not found"
}
Causa: El usuario no tiene formulario (no debería ocurrir, pero es posible)
Solución: Contactar con soporte
No hay campos válidos para actualizar
Estado: 400
Respuesta:
{
"error": "No valid fields to update"
}
Causa: Todos los campos de la petición de actualización están protegidos o son inválidos
Solución: Incluir al menos un campo válido no protegido
Errores de verificación
Token inválido
Estado: 404
Respuesta:
{
"error": "Invalid or expired token"
}
Causa: El token no existe o está mal formado
Solución: Usar el token correcto del correo
Token caducado
Estado: 400
Respuesta:
{
"error": "Token has expired"
}
Causa: El token tiene más de 24 horas
Solución: Solicitar un nuevo registro
Ya procesado
Estado: 400
Respuesta:
{
"error": "Registration already processed",
"status": "approved"
}
Causa: El token ya se usó
Solución: Comprobar el endpoint de estado para el estado actual
Falló la verificación Turnstile
Estado: 400
Respuesta:
{
"error": "Verification failed. Please try again."
}
Causa: Falló o falta el desafío Turnstile en la página de aprobación
Solución: Completar el desafío Turnstile en la página de aprobación
Contraseña demasiado corta
Estado: 400
Respuesta:
{
"error": "Contraseña is required and must be at least 8 characters"
}
Causa: La contraseña tiene menos de 8 caracteres
Solución: Usar una contraseña de 8 o más caracteres
Buenas prácticas de manejo de errores
Lógica de reintento
Para errores transitorios (429, 500), usa backoff exponencial:
async function retryWithBackoff(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.status === 429 || error.status === 500) {
const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
throw new Error("Max retries exceeded");
}
Validar antes de enviar
Valida siempre las entradas antes de llamar a la API:
function validateCorreo electrónico(email) {
return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}
if (!validateCorreo electrónico(operatorCorreo electrónico)) {
throw new Error("Invalid email format");
}
Manejar todos los valores de estado
Al consultar el estado, maneja todos los valores posibles:
const status = response.status;
switch (status) {
case "pending_verification":
// Seguir consultando
break;
case "approved":
// Usar clave API y URL del formulario
break;
case "rejected":
// Registro fallido
break;
case "expired":
// Token caducado, crear nuevo registro
break;
default:
// Estado desconocido
break;
}
Problemas habituales
La clave API no funciona
Síntomas: Errores 401 Unauthorized
Lista de comprobación:
- ✅ Formularioato de clave:
sr_live_+ 64 caracteres hex - ✅ Cabecera Authorization:
Bearer sr_live_xxx - ✅ La clave no ha caducado (90 días por defecto)
- ✅ La clave está activa (no revocada)
Registro atascado en pendiente
Síntomas: El estado sigue en "pending_verification" indefinidamente
Posibles causas:
- El operador no ha revisado el correo
- El correo fue a spam
- El operador rechazó pero el estado aún no se actualizó
Solución: Esperar un tiempo razonable y luego crear un nuevo registro si hace falta
Las actualizaciones del formulario no se aplican
Síntomas: La petición PUT tiene éxito pero el formulario no cambia
Comprobar:
- ✅ Los campos están en la lista permitida (no protegidos)
- ✅ El formato del color es correcto (6 caracteres hex, sin #)
- ✅ Los valores cumplen restricciones (p. ej. longitud del título)