Límites de tasa y errores
Los límites y qué significa cada código de estado.
Un 429 puede provenir de varias capas:
- Nuestro tope de modelos gratuitos: 1 petición por minuto, por modelo gratuito y por usuario.
- Límites del proveedor: el proveedor detrás de un modelo gratuito ha alcanzado su propio tope.
- Presupuestos diarios de tokens en algunos conjuntos gratuitos, que se reinician a medianoche UTC.
- Topes de tokens por minuto, activados por prompts muy grandes.
- Un límite de concurrencia por usuario sobre las peticiones en paralelo.
Los modelos de pago no tienen límites de tasa impuestos por UnoRouter.
Cuando salta el tope de 1 por minuto recibes las cabeceras estándar de límite de peticiones:
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478Retry-After son los segundos que quedan de tu ventana, no un 60 fijo. El mensaje nombra el modelo de pago, que no tiene límite.
Algunos modelos de pago se ofrecen gratis con un tope de tamaño de petición. Los prompts demasiado grandes devuelven 413: Request body too large for gpt-4.1 model. Max size: 8000 tokens.
El tope se aplica solo a la ruta gratuita. El modelo de pago acepta prompts de longitud completa.
Los errores devuelven JSON en el formato de error de OpenAI. code es un identificador estable. A cada mensaje se le añade un id de petición:
{
"error": {
"message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
"type": "new_api_error",
"code": "model_not_found"
}
}Incluye el id de petición en los tickets de soporte. Sirve para localizar tu petición en los registros.
Si aún estás configurando tu clave o la URL base, empieza por Inicio rápido
Los códigos de estado con los que realmente te encontrarás:
| Código | Significado | Qué hacer |
|---|---|---|
400 | Petición no válida: parámetro incorrecto o prompt bloqueado por moderación. | Corrige la petición. Reintentarla sin cambios vuelve a fallar. |
401 | Clave ausente, no válida, caducada o desactivada. | Revisa la cabecera Authorization y la Tokens page. |
402 | El propio límite de gasto de esta clave se ha agotado. | Sube el límite de la clave o crea una clave nueva. |
403 | Saldo agotado, modelo no permitido para esta clave o IP fuera de la lista permitida. | Recarga, o revisa las restricciones de modelo e IP de la clave. |
413 | La petición supera el tope de tamaño de la prueba gratuita del modelo. | Acorta el prompt o cambia al modelo de pago. |
429 | Se disparó un límite de tasa (consulta los tipos más abajo). | Espera los segundos de Retry-After y luego reintenta o cambia de modelo. |
500 | Algo falló por nuestra parte o en el proveedor upstream. | Reinténtalo tras una breve espera. Informa de los 500 persistentes. |
503 | Todos los proveedores saturados o el nombre del modelo no existe. | Lee el mensaje: la saturación se resuelve en minutos, una errata no. |
Dos situaciones muy distintas comparten el estado 503. La primera es una congestión temporal:
HTTP/1.1 503 Service Unavailable
{
"error": {
"message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
"type": "new_api_error",
"code": "get_channel_failed"
}
}get_channel_failed significa que todos los proveedores gratuitos de ese modelo han alcanzado su límite. Se resuelve en minutos: reinténtalo o cambia de modelo. model_not_found significa que el nombre no se resuelve; reintentar nunca ayuda. Busca erratas o consulta el catálogo.
Trata get_channel_failed como reintentable y model_not_found como un error definitivo.
Un modelo que desapareció bajo carga vuelve solo; para recibir aviso en cuanto regrese, vigílalo en Notificaciones
Si tu clave fija grupos de proveedores, aparece un tercer 503 cuando solo tus grupos fijados están caídos, consulta Fijación de grupos
Respeta Retry-After en los 429. Reintenta los 503 get_channel_failed tras una breve espera o cambia de modelo. No reintentes los errores de la clase 400.
Las peticiones fallidas o rechazadas nunca se cobran; cómo funcionan la retención previa y el reembolso se explica en Cuenta y facturación