Errores sobre los que los agentes pueden actuar

Esta página describe errores de la API pública legibles por aplicaciones y agentes de programación. No concede acceso a investigaciones del espacio de trabajo ni al soporte. Para tus solicitudes, consulta la guía de diagnóstico.

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 APIs de Anthropic Messages y Gemini mantienen sus formatos de error nativos, por lo que las extensiones en esta página se aplican únicamente a los errores de Chat Completions y Responses compatibles con OpenAI.

Campos de error opcionalesCopy Anchor Link

Todos los campos a continuación aparecen dentro del objeto error y pueden estar ausentes.

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 desconocidoCopy Anchor Link

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 intentar 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 https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Saldo insuficienteCopy Anchor Link

402 insufficient_balance puede incluir el saldo actual y la cantidad estimada requerida. Su aplicación puede ofrecer un enlace de recarga, un modelo menos costoso o una solicitud más pequeña.

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Modelo no disponibleCopy Anchor Link

503 all_channels_failed o 503 delivery_tier_unavailable no siempre indica un fallo temporal. Si no hay oferta para la operación en el nivel Delivery seleccionado, retryable es false y se omite retry_after. No repita la misma solicitud. Consulte la disponibilidad de la operación y de Delivery mediante GET /v1/models antes de elegir otro modelo. Los nombres similares no garantizan disponibilidad; se omiten las alternativas no verificadas.

{
  "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 tasaCopy Anchor Link

Para 429 rate_limit_exceeded, espere retry_after segundos o utilice el encabezado de respuesta estándar Retry-After.

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Retry after 8s."
  }
}

Contexto demasiado largoCopy Anchor Link

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

Encuentre el formato de API correctoCopy Anchor Link

Lea tokenlab.accepted_request_formats desde GET /v1/models/{model} antes de usar una API específica del modelo.

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 tareaCopy Anchor Link

La API de Models 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 para recommended_for son image, video, music, 3d, tts, stt, embedding, rerank y translation. 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áquinaCopy Anchor Link

Los agentes pueden leer un resumen compacto de la API en:

GET https://api.tokenlab.sh/llms.txt

Incluye una primera solicitud, endpoints comunes, filtros de modelos y orientación sobre el manejo de errores.

Gestionar un error sin repetir la solicitudCopy Anchor Link

El ejemplo envía una sola solicitud, conserva el modelo elegido y muestra información estructurada del error. Los reintentos automáticos del SDK están desactivados. Pide una elección explícita ante las sugerencias de modelos; no repitas automáticamente generaciones aceptadas o con tiempo de espera agotado.

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