Saltar al contenido

Errores y límites

Formato de los errores de la API de Vemudo (problem+json), códigos habituales por estado HTTP, límites de peticiones y tamaños, y cómo reintentar bien.

Por Equipo Vemudo · Actualizado el

Formato de los errores

Todos los errores de /v1 usan application/problem+json (RFC 9457) con un campo code estable. Programa tu lógica contra code, no contra el texto de detail, que puede cambiar.

json
{
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "from_domain_not_verified",
  "detail": "El dominio del remitente no está verificado."
}

Los errores de validación (400 validation_failed) incluyen errors[] con el campo y el motivo de cada fallo. Los mensajes de validación no repiten los valores que enviaste.

json
{
  "status": 400,
  "code": "validation_failed",
  "errors": [{ "field": "emails[3].to", "message": "...", "code": "..." }]
}

Códigos por estado HTTP

EstadoCódigosQué hacer
400validation_failedCorrige la petición. No reintentes igual.
401invalid_api_keyRevisa la clave y la cabecera Authorization.
402plan_quota_exceededCuota agotada. Cambia de plan o espera al siguiente periodo.
403insufficient_scope, organization_not_active, live_key_required, suppression_removal_forbiddenUsa una clave con otro scope o entorno, o hazlo desde el panel.
404not_foundEl recurso no existe, es de otra organización o de otro entorno.
409not_cancellable, idempotency_in_progressEl estado actual no lo permite; espera o consulta el email.
413attachments_too_largeReduce los adjuntos o el tamaño de la petición.
422from_domain_not_found, from_domain_not_verified, scheduled_at_too_far, attachment_type_blocked, idempotency_key_reused, template_not_found, template_not_published, template_render_failed, template_render_too_large, webhook_url_not_allowedLa petición es válida en forma pero no se puede procesar. Corrígela.
429rate_limited, daily_limit_exceededEspera el tiempo de Retry-After.
503suppression_unavailable y otrosFallo temporal. Reintenta con espera.

Errores de agentes y claves de API

Estos códigos son propios de /v1 y de POST /mcp (en /mcp llegan dentro del resultado de la herramienta, con isError: true, en vez de como estado HTTP):

EstadoCódigoQué hacer
403api_key_blockedLa clave está bloqueada por la plataforma. Contacta con soporte.
403agents_blockedLa organización tiene los agentes bloqueados. Contacta con soporte.
403origin_invalidSolo en /mcp: el Origin del navegador no está en la lista permitida. Los clientes de escritorio no envían Origin.
409api_key_limitSe alcanzó el máximo de claves activas del plan (extensions lleva limit y planCode). Revoca una clave o cambia de plan.
429rate_limited (rpm, rpd o concurrencia)Espera Retry-After. extensions lleva limit, window y planCode.
503agents_disabledLos agentes están desactivados temporalmente en la plataforma. Reintenta más tarde.
503rate_limit_unavailableSolo en envíos (POST /v1/emails y lotes): el contador de límites no está disponible. Reintenta con espera.
503openapi_unavailableGET /v1/openapi.json no puede leer el contrato en este momento. Reintenta.

Estos códigos y las dos familias de cabeceras de límite se recogen con su fecha de disponibilidad en el changelog de la API.

Límites de peticiones de agentes (/v1 y /mcp)

Además de los límites de la tabla de arriba, cada clave y organización tiene límites propios de uso como agente, según el plan (ver Planes y cuotas):

  • Peticiones por minuto: por clave.
  • Unidades de coste por día: por organización. El coste de una llamada es 1 salvo las caras (un lote de envío cuesta 5 más 1 por email). El contador se reinicia a las 00:00 UTC.
  • Peticiones simultáneas: por clave.
  • Ráfaga: 10 peticiones por segundo y organización (ya en la tabla de arriba), independiente de los límites del plan.

Al pasarse cualquiera de estos límites llega un 429 rate_limited con Retry-After. Las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset informan del límite de minuto o de día que se esté aplicando; RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (sin el prefijo X-) son las de la ráfaga de 10 por segundo. El día de la cuota diaria es siempre UTC.

Reintentos

  • Reintenta solo errores temporales: 429 (respetando Retry-After), 503 y fallos de red.
  • Usa espera exponencial con algo de aleatoriedad.
  • En envíos, usa siempre una Idempotency-Key para que un reintento no duplique el email (ver Enviar emails).
  • Un 5xx nunca expone detalles internos. Si persiste, escríbenos con la hora y el id del email.

Límites

QuéLímite
Peticiones a la API10 por segundo y organización (cabeceras RateLimit-*).
GET /v1/stats y GET /v1/accountAdemás, 60 por minuto y clave.
Autenticaciones fallidas30 por minuto por IP.
Emails por lote1 a 100.
Tamaño de la petición15 MB en POST /v1/emails, 5 MB en lotes, 100 KB en el resto.
Adjuntos10 por email y 10 MB en total.
HTML / texto512 KB / 256 KB.
Asunto255 caracteres.
Cabeceras personalizadas y etiquetas10 de cada.
Envío programadoHasta 72 horas.
Claves de API25 activas; 20 altas por hora.
Webhooks10 endpoints; 20 altas por hora.
Plantillas200 por organización; 200 versiones por plantilla.
Variables de plantilla32 KB y 10 niveles.
Bajas manuales1.000 altas por hora; 50 bajas por hora.
Claves test100 envíos al día.
EstadísticasHasta 92 días por consulta.
Listadoslimit de 1 a 100 (25 por defecto).

Cabeceras útiles

CabeceraDónde
RateLimit-Limit, RateLimit-Remaining, RateLimit-ResetTodas las respuestas autenticadas.
Retry-AfterRespuestas 429 y algunos 503.
Idempotent-Replayed: trueRespuesta repetida por idempotencia.
WWW-Authenticate: BearerRespuestas 401.
Cache-Control: no-storeLas respuestas de /v1 sobre emails, plantillas, bajas y webhooks, y las consultas.