Gerir erros de faturação e limites de gastos dos clientes

Use o Log-in com ShareAI para identidade e a autorização explícita Pay with ShareAI para ações financiadas pela conta. O openid âmbito por si só nunca autoriza gastos. A inferência de IA requer inference ou uma concessão aprovada e consentida; surcharge pedidos confirmados separadamente. O cliente controla um limite mensal de IA no Console. A sua aplicação não pode alterá-lo.; payments HTTP 402 ·.

Lidar com erros por código#

: a conta de pagamento não tem créditos não expirados suficientes elegíveis para este fornecedor/modelo e pedido. Peça ao cliente para gerir os seus créditos. Alguns créditos têm restrições de fornecedor ou modelo. insufficient_credits: o limite mensal foi atingido, pedidos reservados utilizam a margem disponível, ou o custo deste pedido excederia o limite. Não trate isto como uma limitação de taxa nem tente novamente automaticamente. Peça ao cliente para alterar o limite ou aguarde até.

: a conta de pagamento não tem créditos não expirados suficientes elegíveis para este fornecedor/modelo e pedido. Peça ao cliente para gerir os seus créditos. Alguns créditos têm restrições de fornecedor ou modelo. application_spending_limit_exceededHTTP 429 · reset_at.

: um limite temporário de pedidos/concorrência. Siga oauth_rate_limite backoff limitado. Retry-After HTTP 401 ·. : o consentimento expirou, foi revogado ou já não é válido; obtenha uma nova autorização em vez de pedir um reforço. consent_requiredOs dois erros financeiros utilizam.

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

é o destino de recuperação do cliente; error.type = billing_error. management_url é o seu alias de compatibilidade.; help é uma string decimal exata em EUR e. monthly_limit é UTC. Estão presentes em erros de limite e podem estar ausentes em erros de crédito insuficiente. reset_at Ofereça uma ação visível.

Abrir a conta de pagamento correta#

Gerir faturação usando o URL retornado. O contexto opaco expira após 15 minutos, identifica a conta de pagamento e a conexão originais, e sobrevive ao redirecionamento de início de sessão. O Console verifica as permissões de proprietário/admin do visitante autenticado antes de selecionar essa conta. Não substitua pela página de faturação do proprietário da aplicação, não invente um ID de ator, não anexe um token de acesso, nem redirecione o cliente automaticamente. Use uma lista de permissões para a origem do Console e.

se abrir uma nova aba. O link é navegação, não autorização ou prova de que fundos foram adicionados. Não o armazene como favorito permanente ou em logs públicos. Após expirar, o cliente pode abrir diretamente a página de Faturação. Um novo pedido pode retornar um novo link após o cliente pedir explicitamente para tentar novamente. rel="noopener noreferrer" O ShareAI verifica o limite antes da admissão/vinculação e verifica o custo real da rede mais a sobretaxa de forma atômica na liquidação. Pedidos simultâneos partilham o mesmo limite. Estimativas de entrada reservam margem; o comprimento da saída não é conhecido antecipadamente. Um custo final que exceda a margem restante é rejeitado sem débito de uso ou crédito de sobretaxa para o Builder.

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 e liquidação final#

Para Chat Completions SSE, lide com.

com os mesmos event: error campos de recuperação. Para Responses SSE, lide com error.code e leia response.failed . Uma vez iniciado o stream, o status HTTP já é 200; conteúdo parcial não significa conclusão bem-sucedida. Não marque o resultado como concluído, não realize ações pagas subsequentes nem reenvie automaticamente após um erro terminal. Chat não-streaming, Responses, Embeddings e Images expõem o erro de faturação como um envelope raiz HTTP 402. response.error. Assim que o fluxo começa, seu status HTTP já é 200; conteúdo parcial não significa conclusão bem-sucedida. Não marque o resultado como completo, execute ações pagas downstream ou reenvie automaticamente após um erro terminal. Chat não em fluxo, Respostas, Embeddings e Imagens expõem o erro de cobrança como um HTTP 402 raiz error envelope.

Âmbito e redefinições#

O mês-calendário segue o UTC. O limite é por conta pagante e aplicação, compartilhado entre clientes OAuth, concessões e tokens renovados; um serviço cliente utiliza seu ID de trabalho estável durante rotações de chave de Produção. Apenas o custo liquidado da rede de IA mais a sobretaxa é contabilizado. Assinaturas fixas e compras confirmadas separadamente possuem sua própria autorização de checkout e não consomem este limite de IA. Zero pausa os gastos adicionais de IA; null significa sem limite. Cobranças anteriores são mantidas quando o limite é editado ou a conexão é reautorizada.

Estes são controles do cliente no Console, não um endpoint de desenvolvedor para aumentar orçamentos. Continue aplicando os escopos da concessão, modelos aprovados, preferências de provedores do cliente e os termos de sobretaxa aceitos. Guia de faturação do cliente · API de Checkout.