Errores

Los errores de Quipua tienen siempre esta forma:

JSON
{"error": "insufficient_balance", "message": "Saldo insuficiente: recarga tu cuenta"}
  • error: código estable, pensado para tu código (if err == "insufficient_balance").
  • message: explicación en español para personas. Puede cambiar; no lo compares.

Si el error viene del proveedor del modelo (por ejemplo, parámetros que el modelo no admite, contenido rechazado por su política o una caída sin respaldo), Quipua te lo devuelve con su estado y su cuerpo originales, que siguen el formato de OpenAI o Anthropic ({"error": {"message": …, "type": …}}). En ese caso la respuesta sí lleva x-request-id y x-ci-model-served. Las peticiones que fallan no se cobran.

Códigos

EstadoCódigoCuándo
400invalid_jsonEl cuerpo no es un objeto JSON.
400missing_modelFalta model.
400model_not_chatEl modelo no es de chat (imagen, audio, embeddings…).
400invalid_ahorroValor no válido en x-ci-ahorro.
400auto_not_configuredPediste auto y el equipo no tiene configurado el modelo automático.
400auto_no_modelNingún modelo permitido puede atender la petición (herramientas, imágenes o tamaño).
400invalid_request/v1/memory/proposals sin messages ni facts.
400missing_file, invalid_purpose, invalid_batch_file, invalid_endpoint, invalid_completion_window, invalid_metadata, invalid_input_file, model_not_batchAPI diferida.
401missing_api_keyNo se envió key.
401invalid_api_keyKey desconocida o revocada.
401key_expiredKey caducada (por su fecha o tras una rotación).
402insufficient_balanceSaldo insuficiente para el máximo de la petición. Ver Saldo.
403organization_not_activeLa organización no está activa (alta pendiente o suspendida).
403key_suspendedKey suspendida por Quipua.
403model_not_allowedLa key no tiene permiso para ese modelo.
403team_budget_exceededSe superaría el presupuesto mensual del equipo.
403key_limit_exceededSe superaría el límite de gasto de la key.
403memory_disabledLa organización no tiene activada la memoria.
404model_not_foundModelo inexistente o no disponible para tu organización.
404file_not_found, batch_not_foundFichero o lote inexistente (o de otro equipo).
409file_in_useEl fichero es la entrada de un lote en curso.
410file_expiredEl fichero ya se borró.
413context_too_largeLa entrada supera el tope de contexto de la key.
413file_too_largeFichero de lote de más de 50 MB.
429rate_limitedLímite de peticiones por minuto de la key o de la organización.
429memory_proposals_fullDemasiadas propuestas de memoria pendientes.
500batch_file_unreadableNo se pudo leer un fichero de lote. Contacta con soporte.
502upstream_unavailableNo se pudo contactar con el proveedor del modelo. Reintenta.
502distill_failedFalló la destilación de memoria.
503batch_unavailableLa API diferida no está disponible.

Reintentos

  • Reintenta con espera exponencial: 429, 502, 503 y los 5xx del proveedor.
  • No reintentes sin cambiar algo: 400, 401, 402, 403, 404, 413.
  • Con model: "auto", Quipua ya reintenta por su cuenta con otro modelo del equipo ante caídas o saturación del proveedor (ver Modelo automático).