Saldo, presupuestos y límites
Quipua es prepago: tu empresa recarga saldo y cada petición se descuenta de él. Antes de llamar al modelo se comprueban, en este orden, la key, el límite de peticiones, el tope de contexto, el saldo, el presupuesto del equipo y el límite de gasto de la key. Si algo no se cumple, la petición se rechaza sin llegar al modelo y sin coste.
Reserva por max_tokens (402)
Como el coste real sólo se conoce al terminar, cada petición reserva antes de empezar su coste máximo posible y lo libera al acabar, cuando se cobra lo real. Así, aunque lances muchas peticiones a la vez, nunca se gasta más saldo del que hay.
El máximo se calcula así:
- Entrada: estimada por el tamaño de la petición (unos 3 caracteres por token, a la alta), incluida la memoria de la empresa si se añade.
- Salida:
max_tokens(omax_completion_tokens). Si no lo mandas, la salida máxima por defecto de tu equipo o, si no hay, 4.096 tokens. - Todo al precio del modelo.
Si el saldo disponible (saldo − consumo aún no liquidado − reservas en curso) no cubre ese máximo, la respuesta es:
{"error": "insufficient_balance", "message": "Saldo insuficiente para el máximo de esta petición (0.0610 USD; disponible 0.0420 USD). Recarga o reduce max_tokens."}con estado 402. Si te pasa con saldo todavía positivo, baja max_tokens. Sin saldo, el mensaje es «Saldo insuficiente: recarga tu cuenta».
El saldo se lleva en USD (con el tipo de cambio fijado en cada recarga) y se ve en el panel en tu moneda. Puedes configurar un aviso de saldo bajo en Recargas.
Presupuesto del equipo (403)
Cada equipo puede tener un presupuesto mensual. Se comprueba con lo gastado este mes más lo reservado en peticiones en curso: si la petición podría pasarse, 403 team_budget_exceeded, con un mensaje que dice cuánto queda. Por eso un equipo puede bloquearse un poco antes de gastar el 100 %: baja max_tokens para aprovechar lo que queda.
Los Responsables reciben avisos al 80 % y al llegar al límite, y pueden ampliar el presupuesto o autorizar que el equipo lo supere. Con el modelo automático, el equipo puede pasar a un modelo más económico al acercarse al presupuesto.
Límite de gasto de la key (403)
Si la key tiene límite de gasto (diario, semanal, mensual o total), se comprueba igual que el presupuesto: 403 key_limit_exceeded. Ver Autenticación y keys.
Tope de contexto (413)
Una key puede tener un tope de contexto: la entrada máxima estimada por petición (unos 3,5 caracteres por token del cuerpo que mandas; la memoria de la empresa no cuenta). Si se supera:
{"error": "context_too_large", "message": "La petición tiene unos 152.000 tokens de entrada y esta key admite hasta 100.000. …"}Acorta la conversación o el documento, resúmelo o pide que se amplíe el tope.
Salida máxima por defecto del equipo
Si el equipo tiene salida máxima por defecto, se aplica como max_tokens a las peticiones que no traen ni max_tokens ni max_completion_tokens. Nunca sustituye un valor que mandes tú.
Límite de peticiones (429)
| Ámbito | Por defecto |
|---|---|
| Por key | 60 peticiones por minuto (configurable en cada key) |
| Por organización | 600 peticiones por minuto |
Es una ventana fija por minuto natural. Al superarla: 429 rate_limited, con un mensaje que dice qué límite saltó. Espera al minuto siguiente o reintenta con espera exponencial. Los SDK de OpenAI y Anthropic ya reintentan los 429 automáticamente.
Qué hacer ante cada error
| Estado | Código | Qué hacer |
|---|---|---|
| 402 | insufficient_balance | Recargar o bajar max_tokens. No reintentar sin cambiar nada. |
| 403 | team_budget_exceeded | Bajar max_tokens o pedir al Responsable que amplíe el presupuesto. |
| 403 | key_limit_exceeded | Bajar max_tokens o ampliar el límite de la key. |
| 413 | context_too_large | Reducir la entrada. |
| 429 | rate_limited | Reintentar con espera. |
La tabla completa está en Errores.