Batas pengeluaran gateway aplikasi Claude

Batasi pengeluaran setiap pengembang melalui gateway aplikasi Claude berdasarkan hari, minggu, atau bulan. Tetapkan batas dengan Admin API dan gateway memberlakukannya secara langsung pada setiap permintaan.

Batas pengeluaran membatasi berapa banyak yang dapat dikeluarkan setiap pengembang melalui gateway aplikasi Claude Anda dalam hari, minggu, atau bulan tertentu. Ketika seorang pengembang melampaui batas mereka, gateway mengembalikan 429 pada permintaan berikutnya sampai admin menaikkan batas, atau sampai batas disetel ulang jika nilainya di atas $0. Gunakan batas pengeluaran untuk memberikan setiap pengembang, grup, atau seluruh organisasi batas maksimal pada kredensial yang dibagikan semua orang.

Secara default, gateway aplikasi Claude meneruskan semua inferensi melalui satu kredensial hulu bersama, sehingga tagihan penyedia Anda mengatribusikan semuanya ke kredensial tersebut, bukan ke pengembang individual. Di Amazon Bedrock, atribusi biaya AWS per-pengembang mengubah hal ini. Tanpa batas per-pengembang, satu armada agen yang tidak terkontrol dapat menghabiskan seluruh komitmen organisasi. Batas pengeluaran adalah tampilan per-pengembang gateway dan pemutus sirkuit di atas tagihan bersama tersebut.

Tetapkan batas

Dengan blok admin: yang dikonfigurasi dalam gateway.yaml, gateway melayani Admin API di /v1/organizations/spend_limits dan memberlakukan batas secara langsung pada setiap permintaan inferensi. Batas itu sendiri ditetapkan melalui API tersebut, bukan dalam gateway.yaml; setiap permintaan POST /v1/organizations/spend_limits membuat atau mengganti satu batas dari {scope, amount, period}. API mencerminkan bentuk kawat dari Admin API publik Anthropic untuk titik akhir batas pengeluaran, sehingga klien HTTP yang ditulis terhadap kontrak tersebut dapat menargetkan gateway dengan mengubah URL dasarnya.

Permintaan ini menetapkan default seluruh organisasi sebesar $500 per bulan untuk setiap pengembang:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

Permintaan ini menerapkan batas yang lebih ketat sebesar $100 per hari pada setiap anggota grup contractors:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'

Batas grup atau organisasi adalah default per-kursi yang diwarisi setiap anggota, bukan kumpulan bersama. Per periode, batas efektif pengembang diselesaikan dalam urutan ini: penggantian per-pengguna, kemudian yang paling ketat dari batas grup mereka, kemudian default organisasi, kemudian tidak terbatas. admin.group_limit_mode: max membalik tie-break multi-grup ke yang paling tidak ketat sebagai gantinya.

Autentikasi ke Admin API

Kirim salah satu dari:

• Header x-api-key yang cocok dengan kunci dalam admin.write_keys untuk akses penuh, atau admin.read_keys untuk akses GET-saja. Setiap kunci membawa id yang muncul dalam log audit sebagai admin-key:<id>, jadi berikan Terraform, CI, dan setiap otomasi miliknya sendiri.
• Token pembawa gateway yang klaim groups mencakup salah satu dari admin.admin_groups. Ini adalah akses penuh dan audit sebagai oidc:<sub>, jadi lebih suka untuk admin manusia.

Cara penegakan bekerja

Pada setiap permintaan /v1/messages, gateway menyelesaikan batas pengembang dan pengeluaran periode-ke-tanggal dalam satu kueri Postgres. Pengembang yang melampaui batas apa pun mendapatkan 429 dengan error.type: billing_error dan header x-should-retry: false.

Untuk batas di atas "0", pesan menyebutkan tanggal UTC saat batas tersebut reset. Jika Anda menetapkan admin.blocked_message, gateway menambahkannya, seperti dalam contoh ini:

spend limit reached · resets Dec 1 · request an increase at https://go.example.com/claude-limits

Untuk batas "0", yang tidak dicabut oleh reset, pesan tidak mencantumkan tanggal. Ketika pengembang melampaui beberapa batas sekaligus, pesan menjelaskan batas yang reset terakhir. Respons juga membawa header retry-after dengan jumlah detik hingga periode batas tersebut berakhir.

Sebelum v2.1.319 di server gateway, pesan menyebutkan periode dan waktu reset, seperti spend limit reached (daily; resets 2026-08-08 00:00 UTC). Sebelum v2.1.225, pesannya adalah spend limit reached tanpa periode, waktu reset, atau header retry-after.

Pada v2.1.227 atau lebih baru, referensi protokol di <public_url>/protocol juga mencantumkan header respons batas penggunaan yang tepat dan badan 429.

Batas reset pada batas kalender UTC: setiap hari pada 00:00 UTC, setiap Senin untuk mingguan, dan pada hari pertama untuk bulanan. Gateway tidak pernah memblokir /v1/messages/count_tokens, karena penghitungan token gratis.

Cara permintaan dihargai

Setelah setiap respons, meter penggunaan membaca jumlah token dan menambahkan biaya ke penghitung harian, mingguan, dan bulanan. Meter tidak pernah menyentuh byte yang dikirim ke klien, jadi kegagalan metering tidak dapat merusak respons. Jumlahnya adalah perkiraan USD, pemutus sirkuit daripada faktur; untuk penagihan, rekonsiliasi terhadap pelaporan penggunaan penyedia Anda.

Meter memilih tarif setiap permintaan dalam urutan ini:

1. Baris pricing.overrides yang cocok untuk hulu yang melayani permintaan. Memerlukan v2.1.227 atau lebih baru.
2. Harga daftar untuk ID model hulu, string yang dikirim gateway ke penyedia, ketika tabel biaya Claude Code mengenalinya. Tabel menerima bentuk Anthropic, Amazon Bedrock, Google Cloud's Agent Platform, dan Microsoft Foundry ID.
3. Harga daftar untuk models[].id yang Anda petakan ke ID hulu tersebut, untuk string hulu yang tidak membawa nama model, seperti ARN profil inferensi aplikasi Amazon Bedrock atau nama penerapan Microsoft Foundry. Memerlukan v2.1.218 atau lebih baru.
4. Tingkat model yang tidak dikenal sebesar $5/$25 per juta token input/output, jadi ID yang tidak dapat ditempatkan meter tidak pernah gratis. Gateway memperingatkan saat boot dan sekali per ID saat runtime ketika menggunakan tingkat ini.

Tarif mana pun yang berlaku, meter kemudian mengalikan jumlah dengan pricing.multiplier, default 1. Memerlukan server gateway yang menjalankan Claude Code v2.1.227 atau lebih baru.

Pembatalan klien juga ditagih. Ketika aliran berakhir tanpa bingkai penggunaan akhir hulu, meter menagih perkiraan lantai sekitar empat karakter per token output untuk teks yang sudah dikirim ke klien, jadi membatalkan permintaan lebih awal tidak menghindari batas.

Tarif prompt panjang

Harga daftar untuk Claude Haiku 5.5 memiliki tarif lebih tinggi untuk prompt yang melebihi ambang token. Ketika Haiku 5.5 melayani permintaan yang prompt-nya melebihi ambang tersebut, server gateway yang menjalankan Claude Code v2.1.293 atau lebih baru menghargai seluruh permintaan pada tarif tersebut. Meter menghitung token input, pembacaan cache, dan penulisan cache terhadap ambang tersebut.

Jika salah satu baris pricing.overrides Anda cocok dengan permintaan, tarif baris tersebut berlaku pada panjang prompt berapa pun.

Ketersediaan Postgres

Kueri pra-pemeriksaan Postgres dengan batas waktu dua detik. Jika toko tidak dapat dijangkau atau waktu habis, penegakan gagal terbuka secara default: permintaan dilanjutkan, gateway mencatat peringatan, dan respons tidak membawa header anthropic-ratelimit-unified-*. Atur enforcement.fail_closed_on_error: true untuk gagal tertutup sebagai gantinya, yang mengembalikan 429 billing_error yang sama tetapi dengan pesan spend limit unavailable dan tanpa periode, waktu reset, atau header retry-after. Gagal-terbuka menjaga pemadaman toko agar tidak menjadi pemadaman inferensi; gagal-tertutup menjamin tidak ada pengeluaran yang tidak diukur.

Gagal-terbuka hanya membantu saat penyeimbang beban atau orchestrator Anda masih merutekan lalu lintas ke gateway. Lihat Perilaku pemadaman untuk store.readiness_grace_seconds, yang menjaga replika melewati pemeriksaan kesiapan mereka melalui pemadaman singkat.

Peringatan penggunaan di Claude Code

Claude Code memperingatkan pengembang saat mereka mendekati batas mereka: sekali utilisasi melampaui 75%, dan lagi melampaui 95% dari batas yang paling banyak dikonsumsi. Ketika gateway memblokir permintaan, Claude Code menampilkan pesan 429 gateway apa adanya, termasuk admin.blocked_message Anda. Claude Code juga menampilkan batas tersebut di /usage dan meneruskannya ke skrip baris status pengembang.

Setiap tampilan memerlukan versi Claude Code minimum di mesin pengembang dan di server gateway:

Peringatan dan persentase berasal dari header anthropic-ratelimit-unified-*, yang ditambahkan gateway ke setiap respons /v1/messages yang berhasil untuk pengembang yang memiliki batas. Header selalu menggambarkan batas pengembang itu sendiri: gateway menghapus header rate limit penyedia hulu, yang menggambarkan kuota bersama Anda, dan tidak pernah meneruskannya.

Pengeluaran yang dilihat pengembang adalah perkiraan gateway sendiri, angka yang sama yang digunakan untuk menegakkan batas. Angka ini bukan jumlah dari tagihan penyedia Anda. Claude Code membaca jumlah dolar dengan permintaan terpisah ke gateway, yang tetap dikirimnya meskipun Anda mengatur CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC di mesin pengembang. Sebelum v2.1.295, Claude Code melewati permintaan tersebut ketika variabel itu diatur, dan /usage serta baris status menampilkan persentase dan tanggal reset, tanpa jumlah dolar.

Referensi Admin API

Endpoint di bawah ini disajikan di bawah /v1/organizations/spend_limits.

Konvensi mengikuti Admin API milik Anthropic:

• Sebuah type pada setiap objek
• ID yang berawalan spl_
• Jumlah sebagai string bilangan bulat dalam sen USD; POST menolak currency lain dengan 400
• Amplop error {type: "error", error: {type, message}, request_id}
• Header respons request-id pada setiap respons admin, baik berhasil maupun error; body error juga membawanya sebagai request_id

Setiap mutasi menulis baris sebelum/sesudah ke admin_audit dalam transaksi yang sama, yang diatribusikan ke admin-key:<id> atau oidc:<sub>.

Gateway hanya menyajikan endpoint spend-limits. Surface Admin API lainnya, seperti antrean spend_limit_increase_requests, bukan bagian dari admin API gateway.

/effective

GET /v1/organizations/spend_limits/effective mengembalikan skema SpendSummary milik Anthropic: setiap baris adalah satu principal untuk satu periode, dengan batas yang di-resolve, pengeluaran periode hingga saat ini, dan objek actor. Perbedaan khusus gateway:

• user_id adalah sub OIDC.
• actor.name dan actor.email_address bernilai null hingga permintaan inferensi pertama principal melalui gateway. Gateway tidak memiliki direktori pengguna; gateway mencatat nilai yang terakhir terlihat dari JWT sesi milik setiap pengguna.
• Setiap baris juga membawa array groups, yaitu grup IdP principal yang terakhir terlihat. Ini adalah ekstensi gateway agar UI admin dapat menampilkan setiap tingkat batas yang berlaku; klien berbentuk Anthropic mengabaikannya.
• Tanpa filter user_ids[], endpoint ini mencantumkan principal yang memiliki pengeluaran tercatat, karena gateway tidak dapat menghitung semua anggota organisasi.

Batas yang bersumber dari grup di-resolve terhadap grup yang terakhir terlihat tersebut dengan tie-break group_limit_mode yang sama dengan yang digunakan penegakan, sehingga penampil menunjukkan batas yang benar-benar berlaku.

[!WARNING]

q= dan user_ids[]= dibawa dalam query string GET, sehingga setiap proxy atau load balancer di depannya menangkapnya dalam log akses. Jika kebijakan log PII Anda ketat, bersihkan parameter ini di sana.

/audit

Mengembalikan jejak mutasi spend-limit: siapa yang mengubah batas mana, dengan snapshot sebelum/sesudah, dari yang terbaru. has_more bersifat eksak. Endpoint ini mengikuti konvensi Admin API lokal, bukan bentuk wire first-party.

Paginasi

Daftar mentah dipaginasi berdasarkan after_id dan before_id, yang merupakan ID spl_… yang saling eksklusif; hasil diurutkan berdasarkan waktu pembuatan dan has_more mencerminkan arah penelusuran. /effective dipaginasi berdasarkan token opak next_page yang dikirim kembali sebagai ?page=, dengan principal diurutkan secara menaik sehingga halaman tetap stabil selama pengeluaran sedang dicatat. limit bernilai 1–1000, default 20, pada keduanya. /audit dipaginasi berdasarkan after_id, yaitu id numerik dari event terakhir pada halaman sebelumnya, dan limit-nya memiliki default 100.

Siklus hidup data

Gateway menyimpan empat tabel terkait pengeluaran; sapuan per jam memberlakukan jendela retensi:

Ketika pengembang pergi, hapus batas per-pengguna apa pun melalui DELETE /v1/organizations/spend_limits/{id}; pengeluaran dan baris identitas mereka menua pada jendela retensi di atas. Untuk menghapus satu orang segera, untuk offboarding atau permintaan akses subjek data (DSAR), jalankan DELETE FROM principal_emails WHERE principal = '<sub>' langsung terhadap database gateway. Itu menghapus satu-satunya tabel yang menyimpan email, nama, dan grup mereka. Baris spend dan admin_audit mereferensikan OIDC sub pseudonim saja dan menua pada jendela mereka sendiri.

Terkait

• Konfigurasi admin dan enforcement: mengaktifkan Admin API dan menyetel retensi
• Panduan penerapan: skema Postgres dan panduan cadangan