> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores de la API de BetterToken: códigos HTTP y límites

> Diagnostica errores de la API de BetterToken con el estado HTTP, la respuesta y el ID de solicitud. Resuelve fallos de autenticación, límites y tiempos de espera.

Diagnostica un error de la API de BetterToken combinando el estado HTTP y el cuerpo de la respuesta. Anota el ID de solicitud de `error.message`, corrige los errores de autenticación o configuración antes de reenviar y reintenta solo los fallos identificados como temporales.

## Antes de diagnosticar el problema

Ten a mano el Model ID, la Base URL y la respuesta fallida. Comprueba el estado de la Key y el saldo actual en el [Dashboard de BetterToken](https://bettertoken.ai/workspace). Si aún no has completado una solicitud a un modelo, empieza por los [ejemplos de SDK](/es/guides/sdk-examples.md) o la [guía de configuración de tu herramienta](/es/ai-tools/overview.md).

## Interpreta la respuesta de error

BetterToken devuelve los errores de la API en una estructura JSON. Por ejemplo, una solicitud sin Key puede devolver:

```json theme={null}
{
  "error": {
    "code": "",
    "message": "Token not provided (request id: …)",
    "type": "new_api_error"
  }
}
```

Lee `error.message` aunque `error.code` esté vacío. El ID de solicitud de ese mensaje ayuda a identificar el intento fallido. Una solicitud a `/v1/models` sin Key devuelve `401`; no comprueba si tu modelo puede generar una respuesta.

Anota estos datos antes de contactar con soporte:

| Dato | Qué anotar |
| - | - |
| Estado HTTP | Estado de la respuesta o excepción de red o tiempo de espera del cliente si no hubo respuesta HTTP |
| Cuerpo de la respuesta | JSON de error u otro contenido recibido, sin secretos |
| ID de solicitud | Identificador de `error.message`, si aparece |
| Hora | Fecha, hora y zona horaria del intento |
| Model ID | Valor exacto enviado como `model` |
| Base URL | Base URL configurada y ruta final de la solicitud |

No incluyas tu BetterToken API Key en capturas, mensajes de soporte ni registros compartidos.

## Comprueba el estado HTTP

La tabla recoge los significados generales de HTTP y las API, junto con las guías de configuración enlazadas. No es una lista de códigos específicos de BetterToken; lee la respuesta real antes de elegir una solución.

| Estado | Significado habitual | Qué comprobar primero | ¿Reintentar? |
| - | - | - | - |
| `400` | Solicitud, campo o combinación de parámetros no válidos | Estructura JSON, campos obligatorios, modelo y especificación del endpoint | Corrige primero la solicitud |
| `401` | Credencial ausente, no válida, caducada o revocada | Estado de la Key, espacios y cabecera de autenticación del protocolo | Corrige primero la autenticación |
| `403` | Solicitud rechazada | Mensaje de respuesta, saldo, estado de la Key y configuración del cliente | Resuelve primero el rechazo |
| `404` | Ruta o recurso no encontrado | Base URL, `/v1` duplicado o ausente, ruta final y Model ID exacto | Corrige primero la URL o el recurso |
| `408` / tiempo de espera del cliente | El servidor no recibió la solicitud completa a tiempo o el cliente dejó de esperar | Si se recibió un estado HTTP, ajustes de tiempo de espera, red y estado de la solicitud en el Dashboard | Comprueba si la solicitud terminó antes de decidir |
| `409` / `422`, si se devuelven | Generalmente, conflicto o contenido que no se puede procesar | Detalles de la respuesta y estado o campos enviados | Resuelve primero la causa |
| `429` | Se alcanzó un límite | Cuerpo de la respuesta y cabeceras de reintento; consulta las [preguntas sobre diagnóstico de límites](/es/faq/codex/usage-limit-vs-api-rate-limit.md) | Solo si se identifica un límite temporal de solicitudes |
| `500` | Fallo del servidor | Registro de la solicitud, mensaje y persistencia del fallo | Reintentos limitados si el fallo es temporal |
| `502` / `503` | Fallo del gateway o servicio de origen, o indisponibilidad temporal | Cuerpo de la respuesta y cabecera `Retry-After`, si aparece | Reintentos limitados si el fallo es temporal |
| `504` | El gateway agotó el tiempo de espera de la respuesta del servicio de origen | Registro del Dashboard y si la solicitud terminó | Comprueba la finalización antes de reintentar |

Para errores de protocolo o sufijo, consulta las [preguntas sobre Base URL](/es/faq/model-calling/base-url-config.md). Para dudas sobre caché, consulta las [preguntas sobre facturación de la caché](/es/faq/service-assurance/cache-billing.md).

## Reintenta los fallos temporales

Tras identificar un `429` temporal o un fallo temporal del servidor, usa una espera exponencial con variación aleatoria y límites. Respeta `Retry-After` si se devuelve; si supera tu límite de reintentos, detén el bucle y espera fuera de él. Los reintentos del SDK y los de tu bucle comparten un mismo máximo de intentos; desactiva los del SDK si implementas tu propia política.

No reintentes sin cambios los errores `400`, `401`, `403`, de saldo o de configuración. Un tiempo de espera agotado o un flujo interrumpido no demuestra que la solicitud fallara antes de procesarse. Comprueba primero el **Dashboard**, sobre todo al generar imágenes o en flujos que puedan repetir una acción.

Los siguientes ejemplos envían una solicitud a Chat Completions sin streaming, con un máximo de cuatro intentos. Reintentan los estados HTTP `500`, `502` y `503`. Los reintentos de `429` permanecen desactivados hasta confirmar que se trata de un límite temporal, y se detienen ante tiempos de espera agotados, excepciones de red y `504` para que compruebes si la solicitud terminó. La espera máxima por reintento es de 30 segundos.

### Prepara la solicitud

Copia un Model ID actual del [model plaza](https://bettertoken.ai/pricing) y sustituye los dos valores de ejemplo. Usa un modelo de texto disponible mediante [Chat Completions](/es/api-reference/chat-completions.md).

```bash theme={null}
export BETTERTOKEN_API_KEY="YOUR_API_KEY"
export BETTERTOKEN_MODEL_ID="YOUR_MODEL_ID"
```

El ejemplo de Python usa la biblioteca estándar. Guarda el ejemplo de JavaScript en un archivo `.mjs` y ejecútalo con una versión de Node.js que incluya `fetch` y `AbortSignal.timeout`.

**Python**

```python theme={null}
import json
import os
import random
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime

def retry_after_seconds(value):
    try:
        return max(0.0, float(value))
    except ValueError:
        return max(0.0, (
            parsedate_to_datetime(value) - datetime.now(timezone.utc)
        ).total_seconds())

retry_temporary_429 = False  # Enable only after diagnosing the returned limit.
payload = json.dumps({
    "model": os.environ["BETTERTOKEN_MODEL_ID"],
    "messages": [{"role": "user", "content": "Reply with one word: OK"}],
}).encode()
for attempt in range(4):
    request = urllib.request.Request(
        "https://bettertoken.ai/v1/chat/completions", data=payload,
        headers={
            "Authorization": "Bearer " + os.environ["BETTERTOKEN_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            print(json.load(response)["choices"][0]["message"]["content"])
        break
    except urllib.error.HTTPError as error:
        body = error.read().decode("utf-8", errors="replace")
        retryable = error.code in (500, 502, 503) or (
            error.code == 429 and retry_temporary_429
        )
        if not retryable or attempt == 3:
            raise RuntimeError(f"HTTP {error.code}: {body}") from error
        delay = random.uniform(0, min(8.0, 2.0 ** attempt))
        retry_after = error.headers.get("Retry-After")
        if retry_after:
            delay = max(delay, retry_after_seconds(retry_after))
        if delay > 30:
            raise RuntimeError("Retry-After exceeds this retry budget") from error
        time.sleep(delay)
```

**JavaScript**

```javascript theme={null}
const retryTemporary429 = false; // Enable only after diagnosing the returned limit.
const payload = {
  model: process.env.BETTERTOKEN_MODEL_ID,
  messages: [{ role: "user", content: "Reply with one word: OK" }],
};
for (let attempt = 0; attempt < 4; attempt++) {
  const response = await fetch("https://bettertoken.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BETTERTOKEN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(120000),
  });
  const body = await response.text();
  if (response.ok) {
    console.log(JSON.parse(body).choices[0].message.content);
    break;
  }
  const retryable = [500, 502, 503].includes(response.status) ||
    (response.status === 429 && retryTemporary429);
  if (!retryable || attempt === 3) {
    throw new Error(`HTTP ${response.status}: ${body}`);
  }
  let delay = Math.random() * Math.min(8000, 1000 * 2 ** attempt);
  const retryAfter = response.headers.get("Retry-After");
  if (retryAfter !== null) {
    const seconds = Number(retryAfter);
    const wait = Number.isFinite(seconds)
      ? seconds * 1000 : Date.parse(retryAfter) - Date.now();
    if (!Number.isFinite(wait)) throw new Error("Invalid Retry-After header");
    delay = Math.max(delay, wait, 0);
  }
  if (delay > 30000) throw new Error("Retry-After exceeds this retry budget");
  await new Promise(resolve => setTimeout(resolve, delay));
}
```

Si el cuerpo de la respuesta indica un problema persistente de configuración, saldo o acceso, detén el bucle y corrígelo aunque el estado por sí solo parezca admitir reintentos. Antes de usar este ejemplo breve de texto para otras operaciones, adáptalo a las comprobaciones de finalización de tu aplicación.

## Busca la guía para tu caso

| Síntoma | Guía |
| - | - |
| Error de autenticación, URL o modelo en Claude Code | [Errores frecuentes de Claude Code](/es/ai-tools/claude-code.md#common-errors) |
| Codex pide iniciar sesión o ignora los cambios de proveedor | [Errores frecuentes de Codex CLI / App](/es/ai-tools/codex.md#common-errors) |
| No se puede activar la Key de Cursor o dejan de funcionar los modelos integrados | [Errores frecuentes de Cursor](/es/ai-tools/cursor.md#common-errors) |
| Error de autenticación, `404` o modelo en Cline | [Errores frecuentes de Cline](/es/ai-tools/cline.md#common-errors) |
| Error de proveedor, modelo o configuración del proyecto en OpenCode | [Errores frecuentes de OpenCode](/es/ai-tools/opencode.md#common-errors) |
| El Gateway de Claude Desktop no se conecta | [Errores frecuentes de Claude Desktop](/es/faq/claude-desktop-bettertoken-api.md#common-errors) |
| Aviso de uso de Codex oficial o `429` de la API | [Límite de uso frente a límite de solicitudes de la API](/es/faq/codex/usage-limit-vs-api-rate-limit.md) |
| Los cambios parecen no tener efecto | [Eliminar variables de entorno en conflicto](/es/best-practices.md#clear-conflicting-environment-variables) |
| Salida truncada o error de límite de salida | [Límites de tokens de salida](/es/faq/model-calling/max-tokens.md) |

## Confirma la solución

Envía una solicitud breve y no crítica con el mismo cliente, Base URL y Model ID que fallaron. Confirma que recibes una respuesta normal y busca el registro correspondiente en el **Dashboard**. Comprueba el modelo, el estado, el uso de tokens y el cargo antes de retomar un flujo más amplio.

## Preguntas frecuentes

### ¿Todos los errores 429 requieren esperar y reintentar?

Consulta las [preguntas sobre diagnóstico de límites de uso](/es/faq/codex/usage-limit-vs-api-rate-limit.md) para decidir qué comprobar y si corresponde reintentar tu respuesta.

### ¿Debo aumentar el tiempo de espera tras un fallo?

Primero identifica si el cliente, un proxy o una solicitud al servicio de origen dejó de esperar. Consulta la [guía de tiempos de espera](/es/best-practices.md#set-a-generous-timeout) y verifica el resultado con una solicitud pequeña.

## Recursos relacionados

* [Ejemplos de solicitudes con SDK](/es/guides/sdk-examples.md)
* [Streaming y llamadas a herramientas](/es/guides/streaming-and-tool-calling.md)
* [Referencia de la API](/es/api-reference/introduction.md)
* [Herramientas compatibles](/es/ai-tools/overview.md)
* [Preguntas sobre facturación de la caché](/es/faq/service-assurance/cache-billing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.