Guías principales
Errores sobre los que los agentes pueden actuar
Utilice códigos de error, tiempos de reintento y sugerencias de modelos sin analizar texto
Esta página describe los errores de la API pública legibles por máquina para aplicaciones y agentes de codificación. No otorga acceso a investigaciones de solicitudes de espacio de trabajo ni a soporte técnico. Para una solicitud en su espacio de trabajo, comience con solución de problemas de solicitudes.
Los errores de TokenLab compatibles con OpenAI pueden incluir sugerencias estructuradas para un agente o aplicación. Utilice estos campos cuando estén presentes; no analice el message legible por humanos para decidir qué hacer.
Las API de Anthropic Messages y Gemini mantienen sus formatos de error nativos, por lo que las extensiones en esta página se aplican solo a los errores de Chat Completions y Responses compatibles con OpenAI.
Campos de error opcionales
Todos los campos a continuación aparecen dentro del objeto error y pueden estar ausentes.
| Campo | Tipo | Uso |
|---|---|---|
did_you_mean | string | Reemplazo para un modelo retirado, o el ID de modelo disponible más cercano |
suggestions | array | Modelos que pueden ajustarse a la solicitud |
hint | string | Una breve explicación o acción sugerida |
retryable | boolean | Si la misma solicitud puede tener éxito más tarde |
retry_after | number | Segundos a esperar antes de intentar de nuevo |
balance_usd | number | Saldo actual en USD |
estimated_cost_usd | number | Costo estimado de la solicitud rechazada |
top_up_url | string | Enlace a la página de facturación, en algunos errores de insufficient_balance |
min_top_up_usd | number | Recarga mínima en USD, en algunos errores de insufficient_balance |
Su cliente aún debe manejar cada error por su estado HTTP y code. Trate estos campos adicionales como contexto útil, no como campos obligatorios.
Modelo desconocido
Un modelo mal escrito o no disponible devuelve 400 model_not_found. Si did_you_mean está presente, muéstrelo al usuario o vuelva a intentarlo solo cuando su producto ya tenga permiso para cambiar el modelo seleccionado.
{
"error": {
"message": "Model not found: please check the model name",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found",
"did_you_mean": "gpt-5.6-terra",
"suggestions": [
{"id": "gpt-5.6-terra"},
{"id": "gpt-5.6-luna"}
],
"hint": "Did you mean 'gpt-5.6-terra'? Use GET /v1/models to list all available models."
}
}Saldo insuficiente
402 insufficient_balance puede incluir el saldo actual y el monto estimado requerido, o un enlace de recarga y el monto mínimo de recarga. Su aplicación puede ofrecer un enlace de recarga, un modelo menos costoso o una solicitud más pequeña.
{
"error": {
"message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
"type": "insufficient_balance",
"code": "insufficient_balance",
"retryable": false,
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-5.6-luna"},
{"id": "deepseek-v4.1-flash"}
],
"hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
}
}Modelo no disponible
Un 503 all_channels_failed o 503 delivery_tier_unavailable no siempre significa una interrupción temporal. Si la operación solicitada no tiene suministro en el nivel de entrega (Delivery tier) seleccionado, retryable es false y retry_after se omite. No repita la misma solicitud. Verifique la operación y la disponibilidad de entrega con GET /v1/models antes de seleccionar otro modelo. Los nombres similares no prueban la disponibilidad; las alternativas no verificadas se omiten.
{
"error": {
"message": "This model is unavailable for the requested operation and Delivery tier.",
"type": "all_channels_failed",
"code": "all_channels_failed",
"retryable": false,
"hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
}
}Límite de tasa
Para 429 rate_limit_exceeded, espere retry_after segundos o utilice el encabezado de respuesta estándar Retry-After.
{
"error": {
"message": "Rate limit exceeded (1000/min for user role). Please retry later.",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
}
}Contexto demasiado largo
400 context_length_exceeded no se soluciona enviando la misma solicitud de nuevo. Acorte la entrada o permita que el usuario elija un modelo con una ventana de contexto más grande.
{
"error": {
"message": "This model's maximum context length is 128000 tokens...",
"type": "invalid_request_error",
"code": "context_length_exceeded",
"retryable": false,
"suggestions": [
{"id": "gemini-2.5-pro"},
{"id": "claude-sonnet-5"}
],
"hint": "Reduce your input or switch to a model with a larger context window."
}
}Encontrar el formato de API correcto
Lea tokenlab.accepted_request_formats desde GET /v1/models/{model} antes de usar una API específica del modelo.
| Valor | Endpoint |
|---|---|
openai_chat_completions | /v1/chat/completions |
openai_responses | /v1/responses |
anthropic_messages | /v1/messages |
gemini_generate_content | /v1beta/models/{model}:generateContent |
Un formato aceptado confirma el endpoint. Las herramientas y campos individuales aún pueden variar según el modelo; consulte la página del modelo antes de depender de ellos.
Encontrar un modelo por tarea
La API de modelos puede devolver una lista corta actual para tareas que no son de chat:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image"Los valores válidos de recommended_for son image, video, music, 3d, tts, stt, embedding, rerank, translation y decision. Envíe el ID del modelo elegido explícitamente en la solicitud de creación. TokenLab no lo reemplaza silenciosamente por un modelo diferente.
Resumen legible por máquina
Los agentes pueden leer un resumen compacto de la API en:
GET https://api.tokenlab.sh/llms.txtIncluye una primera solicitud, endpoints comunes, filtros de modelos y orientación sobre el manejo de errores.
Manejar un error sin repetir la solicitud
Este ejemplo realiza una solicitud, conserva el modelo seleccionado e informa información de recuperación estructurada. Los reintentos del SDK están deshabilitados para que su aplicación pueda decidir si un reintento es seguro. Presente sugerencias de modelos para una elección explícita; no repita automáticamente una generación aceptada o que haya agotado el tiempo de espera. Para reintentar una solicitud que agotó el tiempo de espera de forma segura, envíela con una Idempotency-Key, como se muestra en Reintentar de forma segura con una clave de idempotencia.
import os
from openai import OpenAI, APIStatusError
with OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
) as client:
try:
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)
except APIStatusError as exc:
body = exc.body if isinstance(exc.body, dict) else {}
error = body.get("error", body)
if not isinstance(error, dict):
error = {}
print({
"status": exc.status_code,
"request_id": exc.request_id,
"code": error.get("code"),
"hint": error.get("hint"),
"suggested_model": error.get("did_you_mean"),
"retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
})
raise