Guías principales
Manejo de errores de la API
Lea los códigos de error, reintente solo cuando sea útil y conserve el Request ID
Maneje los errores mediante el estado HTTP y el code. El message está escrito para personas y puede cambiar sin previo aviso.
Chat Completions y Responses utilizan un objeto error al estilo de OpenAI. Anthropic Messages y Gemini mantienen sus propios formatos de error, por lo que no debe utilizar un único analizador para toda la API de TokenLab.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Solo message y type están siempre presentes en los errores compatibles con OpenAI creados por TokenLab. Otros campos aparecen cuando son relevantes.
Códigos de estado
| Estado | Significado | Acción típica |
|---|---|---|
400 | Un campo, ID de modelo o entrada no es válido | Corrija la solicitud; no la repita sin cambios |
401 | La API key falta, no es válida, ha caducado o ha sido revocada | Reemplace la clave |
402 | El saldo o el límite de la API key es demasiado bajo | Recargue, aumente el límite o reduzca la solicitud |
403 | Esta clave no puede usar el recurso o modelo, o la cuenta está restringida | Cambie los permisos o el modelo de la clave, o contacte a soporte |
404 | El recurso no existe o ya no está disponible | Verifique el ID y la API key que lo creó |
409 | La Idempotency-Key ya se utilizó: con un cuerpo de solicitud diferente (idempotency_conflict), o para una solicitud cuyo resultado TokenLab no puede devolver (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab no ejecutó la solicitud de nuevo | Use una clave nueva para una solicitud nueva. Para decidir si reintentar con la misma clave, consulte Reintente de forma segura con una idempotency key |
413 | La solicitud o el archivo cargado es demasiado grande | Reduzca la entrada al límite documentado del modelo o endpoint |
429 | Se alcanzó el límite de solicitudes | Espere según Retry-After |
500–504 | Servicio no disponible o fallo de red | Reintente solo cuando retryable sea true; respete retry_after y limite los intentos |
Códigos de error comunes
| Código | Qué significa | Qué cambiar |
|---|---|---|
invalid_api_key | La API key falta, no es válida, está inactiva o fue revocada | Verifique el encabezado Authorization y el valor de la clave |
expired_api_key | La clave ha caducado | Cree o seleccione una clave activa |
insufficient_balance | El saldo de la cuenta no puede cubrir la solicitud | Agregue fondos, reduzca la solicitud o elija un modelo de menor precio |
quota_exceeded | La API key alcanzó su propio límite | Aumente el límite de esa clave o use otra clave autorizada |
model_not_allowed | La clave no puede usar el modelo solicitado | Actualice la lista de modelos de la clave o elija un modelo permitido |
user_suspended, account_restricted | HTTP 403. La cuenta no puede usar la API | Contacte a soporte con el Request ID |
invalid_delivery_policy | HTTP 400. El encabezado X-TokenLab-Delivery-Policy no es auto, verified o official | Envíe uno de los tres valores o elimine el encabezado |
model_not_found | El ID del modelo es desconocido o no está disponible | Lea /v1/models y use un ID de modelo actual |
context_length_exceeded | La entrada es más larga de lo que acepta el modelo | Elimine historial o elija un modelo con una ventana de contexto mayor |
missing_required_parameter | Falta un campo obligatorio. param lo nombra, por ejemplo model en solicitudes de audio e imagen, que no tienen modelo predeterminado | Envíe el campo que nombra param |
invalid_value | Un campo tiene un valor que el modelo no acepta, por ejemplo un valor de reasoning_effort. El mensaje enumera los valores aceptados | Use uno de los valores enumerados |
invalid_response_format_type | HTTP 400. response_format es un objeto sin un type utilizable, o con un type que este endpoint no acepta. param es response_format | Establezca response_format.type en text, json_object o json_schema; con json_schema, envíe también json_schema.name y json_schema.schema |
invalid_image_url | TokenLab no puede usar una URL de imagen: no es una URL HTTP(S) válida o un URI de datos de imagen, o el host de la imagen no devolvió la imagen. param nombra el campo | Envíe una URL de imagen HTTPS pública o un URI de datos compatible |
unsupported_model_capability | Ninguna ruta del nivel de Delivery seleccionado admite un parámetro de solicitud, como la operación, resolution, aspect_ratio, duration, un campo de entrada multimedia, web_search_options o max_tokens. El mensaje nombra cada parámetro que no coincidió y, cuando el modelo los publica, los valores admitidos | Elimine o cambie el parámetro, o elija otro nivel de Delivery o modelo; no repita la solicitud sin cambios |
unpriceable_selection | La solicitud de video omite un selector del cual depende su precio, por lo que TokenLab no puede calcularlo. param nombra el selector | Establezca el campo que nombra param |
model_pricing_unavailable | HTTP 503. La solicitud es válida, pero TokenLab no puede calcular el precio de esta combinación de modelo y operación en las rutas que la solicitud puede usar. No se cobró la solicitud y retryable es false | No repita la solicitud sin cambios; elija otro modelo u operación, o contacte a soporte con el Request ID |
idempotency_conflict | HTTP 409. La Idempotency-Key pertenece a una solicitud diferente. TokenLab no ejecutó esta solicitud | Envíe una solicitud nueva con una clave nueva |
idempotency_replay_unavailable | HTTP 409. La Idempotency-Key ya se utilizó y TokenLab no tiene resultado que devolver. TokenLab no ejecutó esta solicitud de nuevo | Si la primera solicitud aún puede estar ejecutándose, espere y reintente con la misma clave. De lo contrario, envíe una clave nueva. Consulte Reintente de forma segura con una idempotency key |
idempotent_response_not_replayable | HTTP 409. La Idempotency-Key pertenece a una solicitud de creación cuya tarea ya terminó, y TokenLab no puede devolver la respuesta de creación original. El nivel superior del cuerpo de la respuesta incluye task_id, junto a error. TokenLab no ejecutó esta solicitud de nuevo | No repita la solicitud con esta clave. Envíe una clave nueva solo si desea una tarea nueva |
rate_limit_exceeded | Se enviaron demasiadas solicitudes en la ventana actual | Espere según Retry-After |
all_channels_failed | El modelo seleccionado no puede atender esta solicitud | Reintente solo cuando retryable sea true; respete retry_after y limite los intentos |
timeout_error | La solicitud no terminó a tiempo | Reintente solo cuando la operación sea segura de repetir |
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 Delivery seleccionado, retryable es false y retry_after se omite. No repita la misma solicitud. Verifique la disponibilidad de la operación y del Delivery con GET /v1/models antes de seleccionar otro modelo. Los nombres similares no garantizan disponibilidad; las alternativas no verificadas se omiten.
Algunos errores compatibles con OpenAI incluyen campos opcionales did_you_mean, suggestions, alternatives, hint, retryable o retry_after. Consulte Errores sobre los que los agentes pueden actuar.
Cuando una solicitud se ejecutó en una ruta Official y el servicio upstream rechazó la solicitud en sí, como una entrada que no acepta o una decisión de política de contenido, el error también lleva upstream: el message del upstream según se informó, además de code y source (el nombre del servicio upstream) cuando se conocen. Los errores de Anthropic Messages y Gemini llevan el mismo objeto dentro de su propio error. Siga ramificando según code y type; los valores de upstream.code son definidos por el servicio upstream y pueden cambiar.
Decisiones de reintento
| Error | ¿Repetir la misma solicitud? |
|---|---|
400, 401, 402, 403, 404, 413 | No. Cambie la solicitud, las credenciales, el saldo, los permisos o la entrada. |
429 | Sí, después de la demora proporcionada por el servidor. |
500–504 | Reintente solo cuando retryable sea true; respete retry_after y limite los intentos |
| Conexión cerrada antes de cualquier respuesta | Sí, cuando la solicitud aparece en Reintente de forma segura con una idempotency key y tiene una Idempotency-Key: envíela de nuevo con la misma clave y cuerpo. De lo contrario, primero verifique si ya existe una tarea o efecto secundario. |
| Flujo interrumpido después de que llegó la salida | No lo llame una respuesta completa. Repetir puede generar una salida diferente o un segundo cargo. |
Para la creación de imágenes, video, música, 3D y Worlds, guarde el ID de la tarea tan pronto como se devuelva. Si una solicitud de creación agota el tiempo de espera, envíela de nuevo con la misma Idempotency-Key y cuerpo para obtener la tarea original. Sin una clave, verifique el registro de la tarea antes de enviar otra solicitud de creación.
Reintente de forma segura con una idempotency key
Un tiempo de espera o una conexión cerrada no le indican si TokenLab ejecutó la solicitud. Agregue un encabezado Idempotency-Key a las solicitudes enumeradas a continuación. Entonces, un reintento de la misma solicitud no puede ejecutarla ni cobrarla por segunda vez.
- Use un valor único nuevo para cada operación, por ejemplo un UUID. Una clave puede tener hasta 255 caracteres. TokenLab ignora una clave más larga, y la solicitud entonces no tiene protección de idempotencia: un reintento se ejecuta y se cobra de nuevo.
POST /v1/messages/batcheses diferente: rechaza una clave de más de 256 caracteres con400. - Guarde la clave con su propio registro de trabajo antes de enviar la solicitud.
- Cuando reintente, envíe la misma API key, la misma
Idempotency-Keyy el mismo cuerpo. - Después de cualquier respuesta que no sea
409conidempotency_replay_unavailable, no vuelva a usar esa clave. Envíe cualquier intento nuevo con una clave nueva. - Desactive los reintentos del SDK (
max_retries=0), para que su código decida cuándo reutilizar una clave.
Sin el encabezado, cada reintento es una solicitud nueva.
Solicitudes que crean una tarea
Estas solicitudes de creación aceptan Idempotency-Key:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generationsyPOST /v1/worlds/generationsPOST /v1/images/generationsyPOST /v1/images/editscuando devuelven una tareaPOST /v1/responsescon"background": truePOST /v1/messages/batches
Si una solicitud de creación agota el tiempo de espera, envíela de nuevo sin cambios. TokenLab devuelve el resultado de la solicitud de creación original y no crea, despacha ni cobra una segunda tarea. Por lo general, el resultado es la tarea original con el mismo id (para Responses, el objeto de respuesta original), y usted continúa consultándolo. Para tareas de video, música, 3D, Worlds e imágenes, el resultado también puede ser el error original cuando falló la primera solicitud de creación. Si dicha tarea ya terminó y TokenLab no tiene una respuesta de creación almacenada, el reintento devuelve 409 con el código idempotent_response_not_replayable, y el nivel superior del cuerpo de la respuesta incluye task_id.
Si envía un cuerpo diferente con una clave que TokenLab ya aceptó, TokenLab rechaza la solicitud y no crea una tarea. Las solicitudes de creación de video, música, 3D y Worlds devuelven 409 con el código idempotency_conflict. Message Batches devuelve 409 con el tipo de error conflict_error. Para tareas de imágenes y para solicitudes de Responses con background: true, el código de estado y el código de error para este caso no están garantizados. No repita la solicitud con la misma clave.
Chat Completions, Responses y Messages
POST /v1/chat/completions, POST /v1/responses sin background y POST /v1/messages ejecutan una solicitud con una clave dada solo una vez. Un reintento con la misma clave obtiene uno de estos resultados:
| Situación | Resultado |
|---|---|
| La primera solicitud aún se está ejecutando | 409 con el código idempotency_replay_unavailable |
| La primera solicitud terminó después de que su cliente se desconectó. La solicitud no se transmitió, el resultado es de 1 MB o menos, y usted reintenta con el mismo cuerpo dentro de las 24 horas | 200 con el cuerpo de respuesta original y el encabezado Idempotent-Replayed: true. TokenLab no ejecuta ni cobra la solicitud de nuevo |
| La clave se usó de cualquier otra manera, por ejemplo: recibió el resultado, la solicitud se transmitió, el resultado era mayor a 1 MB o pasaron más de 24 horas | 409 con el código idempotency_replay_unavailable |
| El cuerpo es diferente al de la primera solicitud | 409, generalmente con el código idempotency_conflict. Algunas solicitudes devuelven idempotency_replay_unavailable |
Un 409 con cualquiera de los códigos significa que TokenLab no ejecutó la solicitud de nuevo. Una solicitud transmitida con una clave no puede ejecutarse dos veces, pero TokenLab no puede enviar su salida de nuevo.
Este ejemplo reintenta una solicitud de Chat Completions que agotó el tiempo de espera con la misma clave hasta que obtiene el resultado:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Save this key with your job record.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # No response: retry with the same key and body.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# The first attempt can still be running. A later retry returns its result.
raise RuntimeError(f"No result for Idempotency-Key {key}")Si el último intento aún devuelve idempotency_replay_unavailable, TokenLab no puede devolver ese resultado. Envíe la solicitud con una clave nueva solo si una segunda ejecución y un segundo cargo son aceptables.
Conserve el Request ID
Los encabezados de respuesta incluyen un Request ID para el rastreo. Guárdelo junto con el endpoint, el modelo, la hora y su propio ID de usuario o de trabajo. Para el trabajo asíncrono, guarde también task_id y billing_transaction_id cuando estén presentes.
Al contactar a soporte, incluya esos IDs y un ejemplo redactado. Nunca envíe API keys, tokens de gestión, medios privados, URLs firmadas o prompts privados completos.