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 dan memblokir mereka sampai periode disetel ulang atau admin menaikkan batas. Gunakan batas pengeluaran untuk memberikan setiap pengembang, grup, atau seluruh organisasi batas maksimal pada kredensial yang dibagikan semua orang.

Gateway aplikasi Claude meneruskan semua inferensi melalui satu kredensial hulu bersama, sehingga tagihan penyedia Anda mengatribusikan semuanya ke kredensial tersebut, bukan ke pengembang individual. 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.

Pesan menyebutkan periode dan waktu reset, seperti spend limit reached (daily; resets 2026-08-08 00:00 UTC), diikuti oleh admin.blocked_message Anda jika ditetapkan. Ketika pengembang melampaui beberapa batas sekaligus, pesan menyebutkan batas yang reset terakhir. Respons juga membawa header retry-after dengan detik yang tersisa hingga reset tersebut. Sebelum v2.1.225 di server gateway, 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.

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.

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.

Peringatan penggunaan di Claude Code

Claude Code memperingatkan pengembang saat mereka mendekati batas mereka: sekali utilitas 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.

Peringatan bekerja dari header respons:

• Dengan v2.1.225 atau lebih baru di server gateway, setiap respons /v1/messages yang berhasil untuk pengembang yang memiliki batas membawa utilitas batas mereka sendiri dan waktu reset dalam header anthropic-ratelimit-unified-*.
• Dengan v2.1.225 atau lebih baru di mesin pengembang juga, Claude Code membaca header dan menampilkan peringatan.

Header selalu menggambarkan batas pengembang mereka sendiri: gateway menghapus header batas laju penyedia hulu, yang menggambarkan kuota bersama Anda, dan tidak pernah meneruskannya.

Dengan v2.1.251 atau lebih baru di mesin pengembang, Claude Code juga membaca header yang sama untuk menampilkan bilah Spend limit di /usage, dengan persentase batas mereka yang digunakan dan kapan reset, dan untuk menambahkan objek rate_limits.spend_limit ke baris status input. Claude Code menampilkan keduanya sebagai persentase daripada jumlah dolar, dan tidak memerlukan apa pun yang lebih baru dari v2.1.225 di server gateway.

Referensi Admin API

Titik akhir di bawah ini disajikan di bawah /v1/organizations/spend_limits.

Konvensi mencerminkan Admin API Anthropic:

• type pada setiap objek
• ID dengan awalan spl_
• Jumlah sebagai string angka keseluruhan sen USD; POST menolak currency lain apa pun dengan 400
• Amplop kesalahan {type: "error", error: {type, message}, request_id}
• Header respons request-id pada setiap respons admin, sukses atau kesalahan; badan kesalahan juga membawanya sebagai request_id

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

Gateway melayani titik akhir batas pengeluaran saja. Permukaan Admin API lainnya, seperti antrian spend_limit_increase_requests, bukan bagian dari admin API gateway.

`/effective`

GET /v1/organizations/spend_limits/effective mengembalikan skema SpendSummary Anthropic: setiap baris adalah prinsipal untuk periode, dengan batas yang diselesaikan, pengeluaran periode-ke-tanggal, dan objek actor. Perbedaan khusus gateway:

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

Batas bersumber grup diselesaikan terhadap grup terakhir terlihat dengan tie-break group_limit_mode yang sama yang digunakan penegakan, jadi penampil menunjukkan batas yang benar-benar berlaku.

`/audit`

Mengembalikan jejak mutasi batas pengeluaran: siapa yang mengubah batas mana, dengan snapshot sebelum/sesudah, terbaru-pertama. has_more tepat. Titik akhir ini mengikuti konvensi Admin API lokal daripada bentuk kawat pihak pertama.

Paginasi

Daftar mentah halaman berdasarkan after_id dan before_id, yang merupakan ID spl_… yang saling eksklusif; hasil diurutkan berdasarkan pembuatan dan has_more mencerminkan arah traversal. /effective halaman berdasarkan token next_page buram yang diteruskan kembali sebagai ?page=, dengan prinsipal diurutkan naik sehingga halaman tetap stabil saat pengeluaran sedang dicatat. limit adalah 1–1000, default 20, di keduanya. /audit halaman berdasarkan after_id, ID numerik id dari acara terakhir pada halaman sebelumnya, dan limit defaultnya adalah 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