reason de un 429 para saber qué límite detuvo la solicitud; después espera lo que indique Retry-After o cambia el límite. El enrutamiento y los fallbacks reducen los fallos de los proveedores, pero un proveedor o una política del espacio de trabajo o de la clave aún pueden limitar una solicitud.
Todos devuelven
429. Si la aplicación de cuotas del gateway no está disponible durante un momento, el gateway devuelve 503 con indicaciones para reintentar.
Límites del gateway
Cada usuario de cada espacio de trabajo tiene una cuota de solicitudes por minuto, medida en una ventana móvil de un minuto. Las claves de API creadas por el mismo usuario la comparten. Las solicitudes OAuth cuentan para el usuario que ha iniciado sesión, y las claves sin propietario comparten una cuota del espacio de trabajo. La cuota aumenta automáticamente a medida que el espacio de trabajo se consolida. Un espacio de trabajo recibe la fila más alta para la que cumple los requisitos, y los cambios se aplican en pocos minutos:
Los modelos gratuitos también tienen una cuota de 1.500 solicitudes por día UTC de forma predeterminada. Se comparte entre todos los modelos gratuitos y entre todos los espacios de trabajo en los que el mismo usuario envía solicitudes. Las solicitudes a modelos de pago no la usan. Una solicitud gratuita admitida cuenta aunque el proveedor falle después, y los fallbacks de proveedor dentro de una misma solicitud cuentan una sola vez.
Ambos límites se aplican en todas las regiones del gateway y pueden aumentarse para un usuario y un espacio de trabajo concretos. Las operaciones con archivos y las consultas del estado de trabajos usan la cuota por minuto; los endpoints de administración no.
Una solicitud rechazada devuelve
429 con Retry-After en segundos. Espera ese tiempo antes de reintentar.
Límites de la API de administración
Los endpoints de administración, como/v1/keys, /v1/logs y /v1/analytics, comparten una cuota de 200 unidades por minuto por credencial. Cada clave de administración, token OAuth y sesión del panel tiene su propia cuota, y las solicitudes sin credencial comparten una por dirección IP. Los endpoints de modelos, archivos, lotes y trabajos no la usan.
Cada solicitud usa unidades según el trabajo que requiere:
/v1/health y las solicitudes CORS de preflight son gratuitas. Una solicitud que supera la cuota devuelve 429 con rate_limit_exceeded, el motivo management_api_rate_limit y Retry-After: 60. El recuento es aproximado y estas respuestas no incluyen encabezados x-ratelimit-*, así que reparte en el tiempo los scripts masivos en lugar de llevarlos hasta el límite.
Límites de claves y presupuestos
Los límites diarios, semanales o mensuales de solicitudes y gasto de una clave de API, y los presupuestos del espacio de trabajo, devuelven429 con key_limit_exceeded cuando se alcanzan. Los campos reason, limit_window y reset_at del cuerpo indican qué límite fue y cuándo se restablece su ventana, y Retry-After da los segundos que faltan.
Retry-After no aparece cuando el límite no se restablece solo, como un presupuesto vitalicio o una clave con bloqueo suave. No reintentes: aumenta el presupuesto del espacio de trabajo, aumenta el límite de la clave o usa otra clave.
Los propietarios y administradores del espacio de trabajo gestionan los presupuestos con una clave de administración a través de /v1/budgets o en Ajustes → Presupuestos, que muestra el gasto acumulado de cada presupuesto, el porcentaje usado, una proyección para el periodo y cuándo se restablece. Los presupuestos diarios, semanales y mensuales se restablecen en los límites UTC: medianoche, el lunes a las 00:00 y el día 1 del mes.
Las alertas de gasto pueden avisarte antes de que se alcancen estos límites. Una regla de gasto configurada para bloquear devuelve 429 con spend_rule_blocked. Funciona en la medida de lo posible y empieza unos minutos después de que el gasto supere su límite, así que usa límites de claves y presupuestos para topes exactos. Un encabezado x-phaseo-spend-warning significa que puede llegar un bloqueo.
Presupuestos de departamento
Los propietarios y administradores gestionan los presupuestos de departamento conphaseo department-budgets, la API /v1/department-budgets, en Ajustes → Presupuestos o con el recurso phaseo_department_budget del proveedor de Terraform. El gasto de un departamento cuenta las mismas claves y solicitudes OAuth que los límites de velocidad de departamento.
Cuando un departamento ha usado su presupuesto diario, semanal o mensual, las solicitudes con clave de API que cuentan para él devuelven 429 con key_limit_exceeded y el motivo department_daily_cost_budget_reached, department_weekly_cost_budget_reached o department_monthly_cost_budget_reached. Los campos department_id y department_name del cuerpo identifican el departamento, y reset_at y Retry-After indican cuándo se restablece su presupuesto.
- Si la comprobación del presupuesto no está disponible durante un momento, las solicitudes se permiten, así que un departamento puede gastar por encima de su presupuesto durante poco tiempo.
- Los propietarios y administradores reciben una notificación push en el móvil hacia el 80% y de nuevo al 100% de un presupuesto. Para estas alertas, los presupuestos se comprueban cada 15 minutos, así que las solicitudes pueden rechazarse antes de que llegue la alerta del 100%.
Políticas de límite de velocidad
Los administradores del espacio de trabajo pueden crear políticas con nombre que fijanrequests_per_minute, tokens_per_minute y concurrent_requests, y asignarlas a claves, miembros, departamentos o usuarios finales. Gestiónalas con phaseo rate-limits policies y phaseo rate-limits assignments, la API /v1/rate-limits, en Ajustes → Límites de velocidad o con los recursos phaseo_rate_limit_policy y phaseo_rate_limit_assignment del proveedor de Terraform.
Qué cuenta para un departamento. Una clave vinculada a un departamento cuenta solo para ese departamento. Cualquier otra clave cuenta para todos los departamentos a los que pertenece su creador, y las solicitudes OAuth cuentan para todos los departamentos de su usuario. Un miembro con un departamento asignado manualmente cuenta solo para ese departamento. Para que esas claves y solicitudes OAuth cuenten solo para el departamento principal de la persona, configura la atribución de departamento como principal en Ajustes → Notificaciones o con
spend.department_attribution en PATCH /v1/notifications/settings y una clave de administración. Los presupuestos de departamento y las reglas de gasto usan el mismo ajuste.
Cuando se aplican varias políticas, se cuentan todas y la primera que se agota rechaza la solicitud. Las políticas se aplican además de los límites del gateway. Los cambios en las políticas se aplican en aproximadamente un minuto; los cambios de pertenencia a departamentos hechos en el panel o mediante SCIM pueden tardar hasta unos cinco minutos.
Solicitudes y tokens por minuto
Ambos se miden en una ventana móvil de un minuto.tokens_per_minute cuenta los tokens de entrada y salida de cada solicitud cuando termina, incluidas las solicitudes con streaming y las fallidas que usaron tokens. Una solicitud se rechaza en cuanto el uso del último minuto alcanza el límite, así que las solicitudes que ya están en curso pueden llevar el uso por encima. Los fallbacks de proveedor dentro de una misma solicitud cuentan una sola vez.
Una solicitud rechazada devuelve 429 con rate_limit_exceeded, el motivo policy_requests_per_minute o policy_tokens_per_minute, el policy_id, el limit_scope (key, member, department, workspace o end_user) y Retry-After en segundos.
Las respuestas a solicitudes que cubre una política incluyen los encabezados del límite más restrictivo:
Una solicitud rechazada solo incluye los encabezados del límite que la rechazó. El recuento se hace en segundo plano, así que
remaining es aproximado, y los encabezados de tokens aún no incluyen el uso de la propia solicitud.
Solicitudes simultáneas
concurrent_requests limita cuántas solicitudes pueden estar en curso a la vez. Una solicitud ocupa una plaza desde que se admite hasta que su respuesta se ha enviado por completo, incluida toda una respuesta con streaming; los fallbacks de proveedor y de modelo dentro de la solicitud comparten esa plaza. Cuando todas las plazas están ocupadas, la solicitud se rechaza con el motivo policy_concurrent_requests y Retry-After: 1.
Comprobar un límite de simultaneidad espera al contador de la política, lo que añade un poco de latencia. Una plaza cuya liberación se pierde se libera sola después de 15 minutos. Los lotes y las sesiones en tiempo real no se limitan, y una generación de vídeo ocupa una plaza solo mientras está en curso la solicitud que la inicia.
Políticas estrictas
De forma predeterminada, una política falla en abierto: si no se pueden comprobar sus límites, la solicitud se permite. Configurafail_closed para hacerla estricta. Una política estricta comprueba los límites de solicitudes y tokens antes de enviar la solicitud en lugar de hacerlo en segundo plano, lo que los hace exactos pero añade latencia. Si no se pueden comprobar en dos segundos, la solicitud se rechaza con el motivo policy_unavailable.
Los rechazos por simultaneidad y por policy_unavailable no incluyen encabezados x-ratelimit-*.
Límites del proveedor
Las solicitudes BYOK usan los límites de tu cuenta del proveedor. Las solicitudes gestionadas usan capacidad compartida del proveedor, que no es una cuota de tu espacio de trabajo. Phaseo reenvía unRetry-After validado cuando el proveedor lo envía. Las respuestas BYOK también pueden incluir encabezados X-Phaseo-Upstream-RateLimit-*; las solicitudes gestionadas los omiten porque describen capacidad compartida. Los demás encabezados del proveedor no se reenvían. Consulta Códigos de error para ver los códigos 429 del proveedor.
Gestiona una solicitud limitada
- Lee el código de error para distinguir una limitación temporal de un límite, presupuesto o política que necesita un cambio de configuración.
- Respeta
Retry-Aftercuando esté presente. Puede ser un número de segundos o una fecha HTTP; valídalo antes de programar un reintento. - Si no está, usa backoff exponencial con jitter y un retraso máximo.
- Acota los reintentos con un número de intentos y un plazo total. Cancela el trabajo abandonado y libera el cuerpo de cada respuesta fallida antes de reintentar.
- Reduce la simultaneidad si la limitación persiste.
429 por endpoint y modelo, y revisa la frecuencia de fallbacks en los registros de solicitudes. Compáralas con tu configuración de enrutamiento y, para el tráfico BYOK, con las cuotas de tu cuenta del proveedor. Los guardrails controlan qué claves pueden usar qué modelos y proveedores.