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
/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.
{
"title": "Unprocessable Entity",
"status": 422,
"code": "from_domain_not_verified",
"detail": "El dominio del remitente no está verificado."
}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.
{
"status": 400,
"code": "validation_failed",
"errors": [{ "field": "emails[3].to", "message": "...", "code": "..." }]
}Códigos por estado HTTP
400 | validation_failed | |
401 | invalid_api_key | Authorization. |
402 | plan_quota_exceeded | |
403 | insufficient_scope, organization_not_active, live_key_required, suppression_removal_forbidden | |
404 | not_found | |
409 | not_cancellable, idempotency_in_progress | |
413 | attachments_too_large | |
422 | from_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_allowed | |
429 | rate_limited, daily_limit_exceeded | Retry-After. |
503 | suppression_unavailable y otros |
Errores de agentes y claves de API
/v1 y de POST /mcp (en /mcp llegan dentro del resultado de la herramienta, con isError: true, en vez de como estado HTTP):
403 | api_key_blocked | |
403 | agents_blocked | |
403 | origin_invalid | /mcp: el Origin del navegador no está en la lista permitida. Los clientes de escritorio no envían Origin. |
409 | api_key_limit | extensions lleva limit y planCode). Revoca una clave o cambia de plan. |
429 | rate_limited (rpm, rpd o concurrencia) | Retry-After. extensions lleva limit, window y planCode. |
503 | agents_disabled | |
503 | rate_limit_unavailable | POST /v1/emails y lotes): el contador de límites no está disponible. Reintenta con espera. |
503 | openapi_unavailable | GET /v1/openapi.json no puede leer el contrato en este momento. Reintenta. |
Límites de peticiones de agentes (/v1 y /mcp)
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.
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(respetandoRetry-After),503y fallos de red.Usa espera exponencial con algo de aleatoriedad. En envíos, usa siempre una Idempotency-Keypara que un reintento no duplique el email (ver Enviar emails).Un 5xxnunca expone detalles internos. Si persiste, escríbenos con la hora y eliddel email.
Límites
RateLimit-*). | |
GET /v1/stats y GET /v1/account | |
POST /v1/emails, 5 MB en lotes, 100 KB en el resto. | |
test | |
limit de 1 a 100 (25 por defecto). |
Cabeceras útiles
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset | |
Retry-After | 429 y algunos 503. |
Idempotent-Replayed: true | |
WWW-Authenticate: Bearer | 401. |
Cache-Control: no-store | /v1 sobre emails, plantillas, bajas y webhooks, y las consultas. |