Referencia

Errores

Códigos HTTP, tipos de error y cómo reintentar.

Los errores siguen el formato de OpenAI, así que las librerías compatibles los convierten en excepciones con el mensaje correcto:

JSON

{
  "error": {
    "message": "El modelo «gpt-4» no existe o no es tuyo. Consulta GET /api/v1/models.",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}

message está pensado para personas y puede cambiar; para programar, usa el código HTTP y code.

Códigos

HTTP	`code`	Qué ha pasado	Qué hacer
400	—	Petición mal formada: falta `model` o `messages`, un parámetro fuera de rango, `tools`…	Corrige la petición. No reintentes igual.
400	`content_filter`	El contenido no está permitido por la política de uso.	Cambia el contenido.
401	`missing_api_key`	No se ha enviado la cabecera `Authorization`.	Añade `Authorization: Bearer hx_…`.
401	`invalid_api_key`	La clave no existe o se ha revocado.	Comprueba la clave o crea otra.
403	`account_suspended`	La cuenta está suspendida.	Contacta con soporte.
403	`account_closed`	La cuenta está de baja (pedida por su titular) o cerrada.	Si la baja tiene menos de 14 días, inicia sesión en la web para recuperarla.
403	`account_frozen`	La API está bloqueada por una disputa o un contracargo de un pago.	Escríbenos desde Soporte.
404	`model_not_found`	El modelo no existe o el asistente no es tuyo.	Revisa `GET /models`.
413	—	La petición supera 12 MB (normalmente por imágenes).	Reduce las imágenes o usa URL `https://`.
429	`rate_limit_exceeded`	Más de 60 peticiones por minuto con esta clave o con toda tu cuenta.	Espera y reintenta con espera creciente.
429	`too_many_concurrent_requests`	Ya tienes 2 peticiones en curso con esta cuenta.	Espera a que termine alguna.
429	`server_busy`	Sabiuco está atendiendo muchas peticiones a la vez.	Reintenta en unos segundos.
429	`insufficient_quota`	No quedan tokens incluidos en tu plan y el saldo no cubre el coste máximo de la petición.	Baja `max_tokens`, recarga saldo, espera a que se libere cupo (cuenta los últimos 7 días) o hazte Premium.
500	`internal_error`	Error interno de Sabiuco.	Reintenta; si se repite, avisa a soporte con el `x-request-id`.
502	`upstream_error`, `upstream_unavailable`	El motor no ha podido responder.	Reintenta en unos segundos.
502	`stream_interrupted`	La respuesta se ha cortado antes de terminar. Se cobra lo generado hasta ese momento.	Reintenta; para respuestas largas usa `stream: true`.
503	`server_overloaded`	El motor está sobrecargado.	Reintenta respetando `Retry-After`.
504	`upstream_timeout`	El motor no ha empezado a responder a tiempo. No se cobra.	Reintenta en unos segundos.

En una petición sin streaming que tarda más de 20 segundos, la respuesta empieza con código 200 antes de conocerse el resultado: si falla después, el error de la tabla llega en el cuerpo ({"error": …}) con ese 200. Ver Límites y cuotas → Respuestas largas.

Reintentos

Reintenta solo los 429 (excepto insufficient_quota) y los 5xx, con espera exponencial: 1 s, 2 s, 4 s, 8 s… más un pequeño margen aleatorio, y un máximo de 4 o 5 intentos.

Las librerías oficiales de OpenAI ya lo hacen solas (2 reintentos por defecto). Puedes cambiarlo:

Python

cliente = OpenAI(base_url="https://sabiuco.app/api/v1", api_key="hx_...", max_retries=4, timeout=120)

JavaScript

const cliente = new OpenAI({ baseURL: "https://sabiuco.app/api/v1", apiKey: process.env.SABIUCO_API_KEY, maxRetries: 4, timeout: 120_000 })

Las respuestas con razonamiento pueden tardar: usa un tiempo de espera de al menos 120 segundos.