Tangani kesalahan penagihan dan batas pengeluaran pelanggan

Gunakan Log-in dengan ShareAI untuk identitas dan otorisasi eksplisit Pay with ShareAI untuk tindakan yang didanai akun. openid Cakupan saja tidak pernah mengizinkan pengeluaran. Inferensi AI memerlukan inference atau persetujuan, pemberian surcharge yang disetujui; payments permintaan checkout yang dikonfirmasi secara terpisah. Pelanggan mengontrol batas AI bulanan di Console. Aplikasi Anda tidak dapat mengubahnya.

Tangani kesalahan berdasarkan kode#

HTTP 402 · insufficient_credits: akun pembayaran tidak memiliki cukup kredit yang belum kedaluwarsa dan memenuhi syarat untuk penyedia/model dan permintaan ini. Minta pelanggan untuk mengelola kredit mereka. Beberapa kredit memiliki batasan penyedia atau model.

HTTP 402 · application_spending_limit_exceeded: batas bulanan telah tercapai, permintaan yang dicadangkan menggunakan alokasi yang tersedia, atau biaya permintaan ini akan melebihi batas tersebut. Jangan perlakukan ini sebagai batas kecepatan atau coba ulang secara otomatis. Minta pelanggan untuk mengubah batas atau menunggu hingga reset_at.

HTTP 429 · oauth_rate_limit: batas permintaan/konkurensi sementara. Ikuti Retry-After dan backoff terbatas. HTTP 401 · consent_required: persetujuan telah kedaluwarsa, dicabut, atau tidak lagi valid; dapatkan otorisasi baru daripada meminta pengisian ulang.

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

Dua kesalahan finansial menggunakan error.type = billing_error. management_url adalah tujuan pemulihan pelanggan; help adalah alias kompatibilitasnya. monthly_limit adalah string desimal EUR yang tepat dan reset_at adalah UTC. Mereka muncul pada kesalahan batas, dan dapat tidak ada pada kesalahan kredit tidak mencukupi.

Buka akun pembayaran yang benar#

Tawarkan Kelola penagihan tindakan yang terlihat menggunakan URL yang dikembalikan. Konteks opak kedaluwarsa setelah 15 menit, mengidentifikasi akun pembayaran dan koneksi asli, dan tetap ada setelah pengalihan masuk. Console memeriksa izin pemilik/admin pengunjung yang masuk sebelum memilih akun tersebut. Jangan menggantinya dengan halaman penagihan pemilik aplikasi, menciptakan ID aktor, menambahkan token akses, atau mengalihkan pelanggan secara otomatis.

Gunakan daftar izin untuk asal Console dan rel="noopener noreferrer" jika membuka tab baru. Tautan adalah navigasi, bukan otorisasi atau bukti bahwa dana telah ditambahkan. Jangan menyimpannya sebagai bookmark permanen atau di log publik. Setelah kedaluwarsa, pelanggan dapat membuka Penagihan secara langsung. Permintaan baru dapat mengembalikan tautan baru setelah pelanggan secara eksplisit meminta untuk mencoba ulang.

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 dan penyelesaian akhir#

ShareAI memeriksa batas sebelum penerimaan/pengikatan dan memeriksa biaya jaringan aktual ditambah biaya tambahan secara atomik saat penyelesaian. Permintaan bersamaan berbagi batas yang sama. Perkiraan input mencadangkan ruang kepala; panjang output tidak diketahui sebelumnya. Biaya akhir yang akan melebihi alokasi yang tersisa ditolak tanpa debit penggunaan atau kredit biaya tambahan builder.

Untuk Chat Completions SSE, tangani event: error dengan bidang error.code dan pemulihan yang sama. Untuk Responses SSE, tangani response.failed dan baca response.error. Setelah aliran dimulai, status HTTP-nya sudah 200; konten parsial tidak berarti penyelesaian yang berhasil. Jangan menandai hasil selesai, melakukan tindakan berbayar downstream, atau mengirim ulang secara otomatis setelah kesalahan terminal. Chat non-streaming, Responses, Embeddings, dan Images menampilkan kesalahan penagihan sebagai amplop root HTTP 402. error amplop.

Cakupan dan pengaturan ulang#

Bulan kalender berjalan dalam UTC. Batasan berlaku per akun pembayaran dan aplikasi, dibagi di antara klien OAuth, izin, dan token yang diperbarui; layanan klien menggunakan ID kerja stabilnya selama rotasi kunci Produksi. Hanya biaya jaringan AI yang telah diselesaikan ditambah biaya tambahan yang dihitung. Langganan tetap dan pembelian yang dikonfirmasi secara terpisah memiliki otorisasi checkout mereka sendiri dan tidak mengurangi batas AI ini. Nol menghentikan pengeluaran AI tambahan; null berarti tanpa batas. Biaya sebelumnya tetap ada saat batas diubah atau koneksi diotorisasi ulang.

Ini adalah kontrol pelanggan di Console, bukan endpoint pengembang untuk meningkatkan anggaran. Tetap terapkan cakupan izin, model yang disetujui, preferensi penyedia pelanggan, dan ketentuan biaya tambahan yang diterima. Panduan penagihan pelanggan · API Checkout.