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.

Veyra Docs TeamActualizado el 2 min de lecturaVersión 2 · Historial

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.

JSON
{
  "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:

JSON
{
  "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-After ante un 429.
  • Esperen de forma exponencial, con un margen aleatorio, ante 5xx y 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.
APIDesarrolladoresErroresLímites de frecuencia