Guía de la plataforma

Errores y límites de tasa

Qué significa cada código de estado y qué hacer al respecto.

El formato de error

Los errores vuelven como JSON en el formato de error de OpenAI. El mensaje indica qué ocurrió, code es un identificador estable legible por máquina, y se añade un id de solicitud a cada mensaje:

json

{
  "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 siempre el id de solicitud cuando contactes con soporte o abras un ticket en Discord. Nos permite encontrar tu solicitud exacta en los registros.

Códigos de estado de un vistazo

Los códigos de estado con los que realmente te encontrarás:

Código	Significado	Qué hacer
`400`	Solicitud no válida: valores de parámetros incorrectos (por ejemplo max_tokens por debajo del mínimo del modelo) o un prompt bloqueado por la moderación de contenido.	Corrige la solicitud. Reintentarla sin cambios volverá a fallar.
`401`	Problema con la clave: clave de API ausente, no válida, caducada o desactivada.	Comprueba la cabecera Authorization y tu clave en la página de Tokens.
`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`	Acceso denegado: saldo de la cuenta vacío, modelo no permitido para esta clave, o tu IP no está en la lista de permitidas de la clave.	Recarga, o revisa las restricciones de modelo e IP de la clave.
`413`	Solicitud demasiado grande para el tope de la prueba gratuita de este 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.	Reintenta tras una breve espera; los 500 persistentes merecen un informe.
`503`	Todos los proveedores del modelo están ocupados, o el nombre del modelo no existe.	Lee el mensaje: la ocupación se resuelve en minutos, un error de escritura no.

503: ocupado frente a modelo desconocido

Dos situaciones muy distintas comparten el estado 503. La primera es una congestión temporal:

text

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"
  }
}

El código get_channel_failed (todos los proveedores ocupados) significa que todos los proveedores gratuitos de ese modelo están momentáneamente limitados por tasa. Esto se recupera solo en cuestión de minutos: reintenta o cambia de modelo. El código model_not_found (no se ofrece aquí) significa que el propio nombre del modelo no se resuelve, y reintentar nunca ayudará. Comprueba si hay errores de escritura o busca el nombre actual en el catálogo.

Trata el 503 con get_channel_failed como reintento/respaldo y el 503 con model_not_found como un error grave en tu cliente.

Los tipos de límites de tasa

Un 429 puede provenir de varias capas:

Nuestro tope de modelos gratuitos: 1 solicitud por minuto por modelo gratuito por usuario. Un tope de equidad para que los grupos compartidos sobrevivan a las horas punta.
Límites del proveedor upstream: el proveedor detrás de un modelo gratuito alcanzó su propio tope ("temporarily rate-limited upstream", es decir, limitado temporalmente aguas arriba).
Presupuestos diarios de tokens en algunos grupos gratuitos; se restablecen a medianoche UTC.
Topes de tokens por minuto que se activan con prompts muy grandes.
Un límite de concurrencia por usuario cuando se ejecutan demasiadas solicitudes en paralelo.

Los modelos de pago no tienen límites de tasa impuestos por UnoRouter.

El límite de modelos gratuitos en detalle

Cuando se dispara nuestro tope de 1 por minuto, obtienes cabeceras estándar de límite de tasa, para que los clientes puedan retroceder con precisión:

text

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After es dinámico: los segundos reales que quedan en tu ventana, no un 60 fijo. El mensaje de error también nombra al gemelo de pago del modelo, que no tiene límite.

Topes de tamaño de la prueba

Algunos modelos normalmente de pago se ofrecen gratis con un tope de tamaño de solicitud. Los prompts demasiado grandes reciben 413 con un mensaje como: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

El tope se aplica solo a la ruta de prueba gratuita; el modelo de pago acepta prompts de longitud completa.

Orientación sobre reintentos

Respeta Retry-After en los 429. Reintenta el 503 get_channel_failed tras una breve espera, o recurre a otro modelo. No reintentes los errores de clase 400, son deterministas.

Las solicitudes fallidas y rechazadas no se facturan: cualquier retención previa sobre tu saldo se reembolsa cuando la solicitud da error.