Handle billing errors and customer spending limits

Use Log-in with ShareAI for identity and explicit Pay with ShareAI authorization for account-funded actions. The openid scope alone never authorizes spending. AI inference requires inference or an approved, consented surcharge grant; payments requests separately confirmed checkouts. The customer controls a monthly AI limit in Console. Your application cannot change it.

Handle errors by code#

HTTP 402 · insufficient_credits: the paying account lacks enough unexpired credits eligible for this provider/model and request. Ask the customer to manage their credits. Some credits have provider or model restrictions.

HTTP 402 · application_spending_limit_exceeded: the monthly cap is reached, reserved requests use the available allowance, or this request’s charge would exceed it. Do not treat this as a rate limit or retry automatically. Ask the customer to change the limit or wait until reset_at.

HTTP 429 · oauth_rate_limit: a temporary request/concurrency limit. Follow Retry-After and bounded backoff. HTTP 401 · consent_required: consent is expired, revoked or no longer valid; obtain new authorization instead of asking for a top-up.

{
  "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"
  }
}

The two financial errors use error.type = billing_error. management_url is the customer recovery destination; help is its compatibility alias. monthly_limit is an exact EUR decimal string and reset_at is UTC. They are present on cap errors, and can be absent on insufficient-credit errors.

Open the correct paying account#

Offer a visible Manage billing action using the returned URL. The opaque context expires after 15 minutes, identifies the original paying account and connection, and survives the sign-in redirect. Console checks the signed-in visitor’s owner/admin permissions before selecting that account. Do not replace it with the application owner’s billing page, invent an actor ID, append an access token, or redirect the customer automatically.

Use an allowlist for the Console origin and rel="noopener noreferrer" if opening a new tab. The link is navigation, not authorization or proof that funds were added. Do not store it as a permanent bookmark or in public logs. On expiry, the customer can open Billing directly. A fresh request can return a new link after the customer explicitly asks to retry.

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);

Streaming and final settlement#

ShareAI checks the cap before admission/binding and checks the actual network cost plus surcharge atomically at settlement. Concurrent requests share the same cap. Input estimates reserve headroom; output length is not known in advance. A final charge that would exceed the remaining allowance is rejected without a usage debit or builder surcharge credit.

For Chat Completions SSE, handle event: error with the same error.code and recovery fields. For Responses SSE, handle response.failed and read response.error. Once the stream starts its HTTP status is already 200; partial content does not mean successful completion. Do not mark the result complete, perform downstream paid actions or automatically resubmit after a terminal error. Non-streaming Chat, Responses, Embeddings and Images expose the billing error as an HTTP 402 root error envelope.

Scope and resets#

The calendar month runs in UTC. The cap is per paying account and application, shared across OAuth clients, grants and refreshed tokens; a client service uses its stable work ID across Production key rotations. Only settled AI network cost plus surcharge counts. Fixed subscriptions and separately confirmed purchases have their own checkout authorization and do not consume this AI cap. Zero pauses additional AI spending; null means no cap. Past charges are retained when the limit is edited or the connection is reauthorized.

These are customer controls in Console, not a developer endpoint for raising budgets. Continue enforcing the grant’s scopes, approved models, customer provider preferences and accepted surcharge terms. Customer billing guide · Checkout API.