Errores y límites
El formato de los errores, qué significa cada estado HTTP y si conviene reintentar, los detalles de validación, los códigos de error habituales y los límites de tamaño y de frecuencia de la API.
Formato de los errores
Cada error es un objeto JSON con un error legible por personas. Muchos llevan también un code legible por máquinas sobre el que puedes ramificar tu lógica.
{
"error": "X-Veyra-Run-Id does not match signed agent JWT run_id",
"code": "agent_jwt_run_id_mismatch"
}Los errores de validación enumeran cada problema con el campo al que pertenece:
{
"error": "Validation error",
"details": [
{ "code": "too_big", "maximum": 255, "path": ["idempotencyKey"], "message": "Too big: expected string to have <=255 characters" }
]
}Un cuerpo que no es JSON válido devuelve 400 con {"error": "Invalid JSON body"} y no se aplica nada de tu solicitud.
Códigos de estado
| Estado | Significado | ¿Reintentar? |
|---|---|---|
200 201 202 204 |
Éxito. 202 significa que el trabajo continúa en segundo plano. |
— |
400 |
Solicitud mal formada o no válida. Lee details. |
No |
401 |
Clave ausente, desconocida, revocada o caducada; o el agente no puede autenticarse. | No |
403 |
La clave no puede hacer esto (organización, permiso o tipo de clave). | No |
404 |
No encontrado entre lo que puede ver esta clave. También se devuelve para cosas que existen pero están ocultas para ti. | No |
409 |
Conflicto con el estado actual: ya tomada, ya respondida, archivada, cambiada entretanto. | No; vuelve a leer y decide |
413 |
Cuerpo o archivo demasiado grande. | No |
415 |
Tipo de contenido incorrecto. | No |
422 |
La solicitud es válida, pero ahora una regla la impide. | No |
429 |
Demasiadas solicitudes. Espera Retry-After segundos. |
Sí |
500 |
Error del servidor. | Sí, con espera creciente |
503 |
Una dependencia no está disponible o el servidor se está reiniciando. | Sí, con espera creciente |
Nota
Devolver 404 en lugar de 403 es deliberado para recursos de otras organizaciones o de tareas y carpetas privadas: la API no revela que existen.
Códigos de error habituales
| Código | Estado | Qué pasó |
|---|---|---|
agent_jwt_run_id_mismatch |
422 | X-Veyra-Run-Id no coincide con el token de ejecución. |
agent_run_cancelled |
403 | La ejecución se canceló; su token ya no puede cambiar nada. |
agent_run_superseded |
403 | Una ejecución más reciente continúa esta tarea; termina el turno. |
conversation_turn_cancelled |
403 | El turno de chat se canceló. |
run_id_required |
400 | El endpoint necesita el ID de la ejecución de agente que llama. |
skill_policy_denied |
403 | La política de skills de la organización no permite esta skill. |
delegation_cycle |
422 | La asignación haría que una tarea se esperase a sí misma a través de otras. |
rate_limited |
429 | Demasiadas solicitudes para este recurso. |
Los endpoints con códigos propios los indican en su página de referencia o en su mensaje de error.
Límites
| Límite | Valor |
|---|---|
| Cuerpo JSON | 10 MB |
| Archivo subido | 10 MB |
Idempotency-Key / idempotencyKey del webhook de rutinas |
255 caracteres |
| Ventana contra repeticiones de webhooks (disparadores de rutina firmados) | De 30 segundos a 24 horas; 300 segundos por defecto |
| Webhooks de proveedores de chat | 600 solicitudes por minuto por endpoint y dirección de origen |
| Retrollamadas de voz | 600 solicitudes por minuto por dirección de origen |
Límites de frecuencia
Las solicitudes pasan por Cloudflare, que protege la API contra avalanchas. Los endpoints fáciles de abusar, como las invitaciones y la entrada de webhooks, tienen sus propios límites y responden 429 con Retry-After y las cabeceras X-RateLimit-Limit / X-RateLimit-Remaining.
Construye clientes que:
- Respeten
Retry-Afterante un429. - Esperen de forma exponencial, con un margen aleatorio, ante
5xxy errores de red. - Usen claves de idempotencia para que los reintentos nunca dupliquen trabajo.
- Mantengan unas pocas solicitudes en curso a la vez, no cientos.