Solución de problemas

La forma del error coincide con el protocolo que llamaste. /v1/chat/completions y /v1/responses devuelven errores con formato OpenAI; /v1/messages devuelve errores con formato Anthropic. Los códigos de estado HTTP son idénticos en los tres protocolos.

Formato de respuesta de error

Formato OpenAI (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Formato Anthropic (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · Error de autenticación authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

Causas

• Falta el encabezado Authorization: Bearer (o X-API-Key) — mensaje: missing API key in Authorization header or X-API-Key.
• La clave no coincide con ninguna clave activa — mensaje: invalid API key.
• La clave ha caducado — mensaje: API key expired.

Solución

1. Envía Authorization: Bearer sk-syn-… (o X-API-Key: sk-syn-…).
2. Confirma que la clave está activa en la consola y que se copió por completo.

400 · Solicitud no válida invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

Causas

• Falta el campo model, o el cuerpo JSON está vacío o mal formado.

Solución

1. Incluye un model y un cuerpo JSON bien formado. Consulta la referencia de Chat Completions.

403 · Cuota agotada quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

Causas

• El saldo prepago de la clave o del espacio de trabajo se ha agotado.

Solución

1. Recarga el saldo del espacio de trabajo. Nota: Synthorai devuelve 403 quota_exhausted cuando el saldo se agota, no 429 — por lo que el backoff exponencial no ayudará; solo una recarga lo resuelve.

403 · Cumplimiento — sin compartir datos compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

Causas

• Tu espacio de trabajo tiene no_provider_data_share habilitado, y el modelo solicitado solo lo ofrece un proveedor que exige retención/uso compartido de datos (p. ej., un modelo de Bedrock o Vertex solo con uso compartido de datos).

Solución

1. Enruta la solicitud a un modelo sin retención, o desactiva el interruptor de cumplimiento del espacio de trabajo si el uso compartido de datos es aceptable para esa carga. La clase de retención es un criterio de enrutamiento por modelo — consulta el desglose de la retención de 30 días.

429 · Límite de tasa alcanzado rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

Causas

• Superaste el límite de solicitudes por minuto (RPM). El mensaje indica el límite exacto.

Solución

1. Espera y reintenta con backoff exponencial + jitter (fragmento abajo). Solicita un límite mayor si necesitas rendimiento sostenido.

502 · Sin canal para el modelo upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

Causas

• El id del modelo no coincide con ningún canal enrutable para tu espacio de trabajo: un error tipográfico, un modelo retirado o uno que tu plan no puede alcanzar.

Solución

1. Comprueba el id exacto en la lista de modelos en vivo. Si un modelo se retiró recientemente, elige uno vigente.

BYOK: errores del proveedor upstream

Con bring-your-own-key, la solicitud se ejecuta en tu cuenta del proveedor (AWS Bedrock, Google Vertex AI o la API de Anthropic), por lo que Synthorai transmite el error original del proveedor sin cambios — las respuestas llevan usage.is_byok: true. La solución está en la consola o configuración de ese proveedor, no en la pasarela. Los más comunes son los ajustes de acceso a modelos y de uso compartido de datos a nivel de cuenta:

Errores del proveedor upstream

Estos se transmiten desde el proveedor del modelo con su propio estado HTTP y type. Solo 500 y 529 indican el lado del proveedor; trátalos (y 429) como transitorios y reintenta, mientras que los 4xx reflejan la solicitud. Referencia completa: la documentación de errores de Anthropic.

Límites de tasa

Los límites de tasa se aplican por clave API para garantizar un uso justo entre todos los usuarios.

Límites predeterminados

¿Presupuestando el rendimiento de tokens con precios reales por token? Ejecuta tu carga de trabajo en la calculadora de costes de API LLM.

Gestión de errores 429

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

¿Un 502 o sobrecarga en un modelo? Elige una alternativa en la comparación de precios de modelos — cada modelo enrutable y su precio por token en una sola tabla.