Gestiona errores de facturación y límites de gasto del cliente

Usa Iniciar sesión con ShareAI para la identidad y la autorización explícita Pagar con ShareAI para acciones financiadas por cuenta. El openid alcance por sí solo nunca autoriza el gasto. La inferencia de IA requiere inference una concesión aprobada y consentida surcharge ; payments solicitudes con confirmaciones de pago separadas. El cliente controla un límite mensual de IA en la Consola. Tu aplicación no puede cambiarlo.

Manejar errores por código#

HTTP 402 · insufficient_credits: la cuenta de pago no tiene suficientes créditos no vencidos elegibles para este proveedor/modelo y solicitud. Pide al cliente que gestione sus créditos. Algunos créditos tienen restricciones de proveedor o modelo.

HTTP 402 · application_spending_limit_exceeded: se alcanzó el límite mensual, las solicitudes reservadas usan la asignación disponible, o el cargo de esta solicitud lo excedería. No trates esto como un límite de tasa ni reintentes automáticamente. Pide al cliente que cambie el límite o espera hasta que reset_at.

HTTP 429 · oauth_rate_limit: un límite temporal de solicitudes/concurrencia. Sigue Retry-After y retrocesos limitados. HTTP 401 · consent_required: el consentimiento ha expirado, ha sido revocado o ya no es válido; obtén una nueva autorización en lugar de pedir una recarga.

{
  "error": {
    "type": "billing_error",
    "code": "application_spending_limit_exceeded",
    "message": "This application's monthly AI spending limit has been reached or this request would exceed it. Manage the limit or wait for the next month.",
    "management_url": "https://console.shareai.now/?shareai_billing_context=OPAQUE_SHORT_LIVED_VALUE",
    "help": "https://console.shareai.now/?shareai_billing_context=OPAQUE_SHORT_LIVED_VALUE",
    "monthly_limit": "50",
    "reset_at": "2026-10-01T00:00:00Z"
  }
}

Los dos errores financieros usan error.type = billing_error. management_url es el destino de recuperación del cliente; help es su alias de compatibilidad. monthly_limit es una cadena decimal exacta en EUR y reset_at es UTC. Están presentes en errores de límite, y pueden estar ausentes en errores de créditos insuficientes.

Abrir la cuenta de pago correcta#

Ofrece una Administrar facturación acción visible usando la URL devuelta. El contexto opaco expira después de 15 minutos, identifica la cuenta de pago y conexión original, y sobrevive a la redirección de inicio de sesión. La Consola verifica los permisos de propietario/administrador del visitante que inició sesión antes de seleccionar esa cuenta. No lo reemplaces con la página de facturación del propietario de la aplicación, inventes un ID de actor, añadas un token de acceso o redirijas automáticamente al cliente.

Usa una lista de permitidos para el origen de la Consola y rel="noopener noreferrer" si abres una nueva pestaña. El enlace es navegación, no autorización ni prueba de que se añadieron fondos. No lo almacenes como un marcador permanente ni en registros públicos. Al expirar, el cliente puede abrir Facturación directamente. Una nueva solicitud puede devolver un nuevo enlace después de que el cliente pida explícitamente reintentar.

const response = await fetch("https://api.shareai.now/api/v1/chat/completions", options);
const body = await response.json();
const error = body.error;
if (response.status === 402 && error?.type === "billing_error") {
  const message = error.code === "application_spending_limit_exceeded"
    ? "Your monthly limit for this app has been reached."
    : "Your ShareAI account needs eligible credits.";
  showBillingMessage(message);
  if (error.management_url) {
    const target = new URL(error.management_url);
    if (target.origin === "https://console.shareai.now") {
      // Render a user-activated link; never silently open it or retry spending.
      showManageBillingLink(target.href);
    }
  }
  return;
}
if (!response.ok || error) throw new Error(error?.message || "Request failed");
renderAnswer(body);

Transmisión y liquidación final#

ShareAI verifica el límite antes de la admisión/asignación y verifica el costo real de la red más el recargo de forma atómica en la liquidación. Las solicitudes concurrentes comparten el mismo límite. Las estimaciones de entrada reservan margen; la longitud de salida no se conoce de antemano. Un cargo final que exceda la asignación restante se rechaza sin un débito de uso ni un crédito de recargo del Builder.

Para Chat Completions SSE, maneja event: error con los mismos error.code y campos de recuperación. Para Responses SSE, maneja response.failed y lee response.error. Una vez que comienza la transmisión, su estado HTTP ya es 200; el contenido parcial no significa finalización exitosa. No marques el resultado como completo, realices acciones pagadas posteriores ni reenvíes automáticamente después de un error terminal. Los servicios no transmitidos de Chat, Responses, Embeddings e Images exponen el error de facturación como un HTTP 402 raíz error sobre.

Alcance y reinicios#

El mes calendario se ejecuta en UTC. El límite es por cuenta de pago y aplicación, compartido entre clientes OAuth, concesiones y tokens actualizados; un servicio cliente utiliza su ID de trabajo estable a través de rotaciones de claves de Producción. Solo se cuenta el costo de la red de IA liquidado más el recargo. Las suscripciones fijas y las compras confirmadas por separado tienen su propia autorización de pago y no consumen este límite de IA. Cero pausa el gasto adicional de IA; null significa sin límite. Los cargos pasados se mantienen cuando se edita el límite o se vuelve a autorizar la conexión.

Estos son controles del cliente en la Consola, no un punto final para desarrolladores destinado a aumentar presupuestos. Continúa aplicando los alcances de la concesión, los modelos aprobados, las preferencias del proveedor del cliente y los términos de recargo aceptados. Guía de facturación para clientes · API de pago.