Errores y límites
Formato de error#
Todos los errores responden con el mismo cuerpo JSON:
400
{
"statusCode": 400,
"message": "Field \"Teléfono\" is required",
"error": "Bad Request",
"timestamp": "2026-09-29T18:04:12.511Z",
"path": "/api/v1/public/forms/mi-constructora/contacto/submit",
"requestId": "sitio-web-7f3a9c"
}message puede ser un texto o una lista de textos (cuando fallan varias validaciones). Envía tu propio encabezado X-Request-Id en cada petición: YAVE lo devuelve en requestId y lo usa en sus registros, así podemos encontrar tu petición exacta si nos pides ayuda.
Códigos HTTP#
| Código | Significado | ¿Reintentar? |
|---|---|---|
200 · 201 | Éxito. | — |
400 | Petición inválida: falta un campo, sobra una propiedad o un valor no tiene el formato esperado. | No. Corrige la petición. |
401 | Falta la credencial o no es válida. | No. |
403 | La credencial es válida pero no tiene permiso para esa acción. | No. |
404 | El recurso no existe o no está publicado (formulario pausado, sitio inactivo). | No. |
429 | Superaste el límite de peticiones. | Sí, después de retryAfter segundos. |
500 · 502 · 503 | Error de nuestro lado o mantenimiento. | Sí, con espera exponencial. |
Límites de uso#
Los límites se cuentan por dirección IP y por endpoint. Además, ningún cliente puede superar 30 peticiones por segundo en total.
| Tipo de petición | Límite | Si lo superas |
|---|---|---|
| Lecturas (GET) | 300 por minuto | Bloqueo de 30 s |
| Escrituras (POST, PUT, PATCH, DELETE) | 500 por minuto | Bloqueo de 30 s |
| Formularios de contacto del catálogo público | 5 por minuto | 429 hasta que pase el minuto |
Cada respuesta incluye el estado de tu cupo:
Encabezados
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1790700312000 # epoch en milisegundos429
{
"statusCode": 429,
"message": "Too many requests from this IP. Please try again later.",
"error": "Too Many Requests",
"retryAfter": 30
}Cargas masivas
¿Vas a migrar miles de leads? No los mandes por el API en un bucle: escríbenos y el equipo de YAVE hace la importación desde un archivo, con deduplicación y asignación incluidas.Reintentos recomendados#
- Reintenta solo
429,5xxy errores de red o timeout. - Espera exponencial con algo de azar: 2 s, 8 s, 30 s, 2 min. Máximo 5 intentos, y después guarda el envío para revisarlo.
- Usa un timeout de cliente de 15 a 30 segundos.
- Para crear leads, incluye siempre el teléfono: así un reintento no crea duplicados (ver duplicados).
Llamadas desde el navegador (CORS)#
| Endpoint | Desde el navegador |
|---|---|
/public/forms/* | Sí, desde cualquier dominio. |
/public/whatsapp-widget/* | Sí, desde cualquier dominio (lo usa el script). |
/public/organizations/* | Solo desde dominios autorizados (por ejemplo, el dominio propio verificado de la organización). |
/webhooks/custom | No. Llámalo desde tu servidor: lleva la API key. |
Versiones y cambios#
El API vive bajo /api/v1. Podemos agregar campos nuevos a las respuestas en cualquier momento, así que tu código debe ignorar los campos que no conoce. Los cambios que rompan compatibilidad se anunciarán con anticipación.