Error Claude API
Pahami kode status HTTP, bentuk respons error, dan ID permintaan yang dikembalikan oleh Claude API, serta tangani error dengan exception bertipe dari SDK.
Error HTTP
API mengikuti format kode error HTTP yang dapat diprediksi:
-
400 -
invalid_request_error: Terdapat masalah pada format atau konten permintaan Anda. API mungkin juga menggunakan tipe error ini untuk kode status 4XX lain yang tidak tercantum di bagian ini. API juga mengembalikan 400 ketika penggunaan mencapai batas pengeluaran yang Anda tetapkan untuk organisasi atau workspace. Batas pada workspace Claude Code merupakan pengecualian: batas tersebut dapat mengembalikan 429 sebagai gantinya. Jika pesannya menyebutkan masalah pada permintaan Anda, cari masalah tersebut di Error validasi umum. -
401 -
authentication_error: Terdapat masalah pada kunci API Anda (misalnya, formatnya salah, telah dicabut, atau kedaluwarsa; lihat Kedaluwarsa kunci). Di Claude Platform on AWS, ini juga dapat menunjukkan masalah pada kredensial AWS atau tanda tangan SigV4 Anda.Error 401 yang pesannya diawali dengan
CORS requests are not allowed for this Organizationbukanlah masalah pada kunci API Anda. Permintaan tersebut menyertakan headerOrigin, yang ditambahkan oleh browser, dan organisasi Anda tidak dapat memanggil Claude API langsung dari browser. Pesan tersebut berlanjut denganbecause of custom retention settingsataubecause of its settings. Yang pertama hanya muncul untuk pengaturan retensi data seperti “zero data retention” (retensi data nol), atau ZDR; yang kedua adalah kasus umum, yang mencakup Compliance API. Tidak ada perubahan pada permintaan browser yang dapat memperbaikinya, jadi kirimkan permintaan dari back end Anda sendiri; lihat Aplikasi berbasis browser. -
402 -
billing_error: Terdapat masalah pada informasi penagihan atau pembayaran Anda. Periksa detail pembayaran Anda di Claude Console, atau di AWS Marketplace jika Anda menggunakan Claude Platform on AWS. -
403 -
permission_error: Kunci API Anda tidak memiliki izin untuk menggunakan sumber daya yang ditentukan. Periksa akses organisasi dan pengaturan workspace Anda di Claude Console. -
404 -
not_found_error: Sumber daya yang diminta tidak ditemukan. Periksa path endpoint dan ID sumber daya apa pun di URL permintaan. -
409 -
conflict_error: Permintaan bertentangan dengan status sumber daya saat ini. Misalnya, sumber daya dimodifikasi secara bersamaan, atau nilai yang harus unik sudah digunakan. Selesaikan konflik tersebut, lalu coba ulang permintaan. -
413 -
request_too_large: Permintaan melebihi jumlah byte maksimum yang diizinkan. Lihat Batas ukuran permintaan untuk batas maksimum per endpoint. -
429 -
rate_limit_error: Organisasi Anda telah mencapai “rate limit” (batas laju), mencapai batas pengeluaran bulanan tingkat penggunaannya, atau mencapai batas pengeluaran pada workspace Claude Code. Error 429 akibat batas pengeluaran tingkat tidak memiliki headerretry-afterdan akan terus gagal hingga akses dipulihkan; lihat Mencapai batas pengeluaran Anda untuk cara mengenalinya. Peningkatan penggunaan yang tajam juga dapat menyebabkan error 429 meskipun Anda masih berada di bawah batas laju Anda; lihat “Ramp limits” (batas ramp). -
500 -
api_error: Terjadi error tak terduga di dalam sistem Anthropic. Coba ulang permintaan dengan “exponential backoff” (penundaan eksponensial); jika error berlanjut, hubungi dukungan dengan menyertakan ID permintaan. Jika tipe error-nya justrutimeout_error, lihat entri 504. -
504 -
timeout_error: Permintaan mengalami timeout saat diproses. API juga mengembalikantimeout_errordengan kode status lain, seperti 500 ketika permintaan mencapai batas waktu server sebelum respons dimulai. Untuk permintaan Messages API yang berjalan lama, gunakan Messages API dengan streaming. Lihat Permintaan panjang untuk opsi lainnya. -
529 -
overloaded_error: API sedang kelebihan beban untuk sementara.
SDK resmi secara otomatis mencoba ulang kegagalan sementara (seperti error koneksi, batas laju, dan error server 5xx) dengan exponential backoff, dua kali secara default, dengan mematuhi header retry-after jika ada. Klien SDK menerima max_retries untuk mengonfigurasi atau menonaktifkan perilaku ini.
Saat menerima respons streaming melalui “server-sent events” (peristiwa yang dikirim server), atau SSE, error dapat terjadi setelah API mengembalikan respons 200. Dalam kasus tersebut, penanganan error tidak mengikuti mekanisme standar ini. Lihat Event error untuk bentuk error di tengah stream.
Batas ukuran permintaan
Claude API pihak pertama menerapkan batas ukuran permintaan berikut. Untuk platform lain, lihat ikhtisar API.
| Tipe endpoint | Ukuran permintaan maksimum |
|---|---|
| Messages API | 128 MB |
| Token Counting API | 128 MB |
| Batch API | 256 MB |
| Files API | 500 MB |
Jika Anda melebihi batas ini, Anda akan menerima error 413 request_too_large. Pada Claude API pihak pertama, Cloudflare mengembalikan error ini sebelum permintaan mencapai server API.
Bentuk error
API selalu mengembalikan error sebagai JSON, dengan objek error tingkat atas yang selalu menyertakan nilai type dan message. Respons juga menyertakan field request_id untuk memudahkan pelacakan dan debugging. Misalnya:
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "The requested resource could not be found."
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}Berdasarkan kebijakan pembuatan versi API, nilai dalam objek-objek ini dapat bertambah, dan nilai type baru dapat muncul.
Tipe error SDK
SDK resmi memunculkan exception bertipe untuk error-error ini alih-alih mengembalikan JSON mentah. Misalnya, error 404 muncul sebagai anthropic.NotFoundError. Go SDK memiliki satu tipe error untuk semua status, yaitu *anthropic.Error: lakukan percabangan berdasarkan StatusCode. Tangkap kelas bertipe dari SDK alih-alih mencocokkan string pesan error, dengan menangani kelas yang paling spesifik terlebih dahulu. Halaman SDK Anda mendokumentasikan hierarki exception secara lengkap:
ID permintaan
Setiap respons API menyertakan header request-id yang unik. Header ini berisi nilai seperti req_018EeWyXxfu5pfWkrYcMdjWG. Pengenal yang sama muncul sebagai field request_id dalam body respons error. Saat menghubungi dukungan mengenai permintaan tertentu, sertakan ID ini untuk membantu menyelesaikan masalah Anda dengan cepat.
Pada Claude Platform on AWS, respons menyertakan dua ID permintaan: ID permintaan AWS (x-amzn-requestid, primer, diindeks di CloudTrail) dan ID permintaan Anthropic (request-id, sekunder). Gunakan ID permintaan AWS untuk pencarian CloudTrail dan ID permintaan Anthropic untuk tiket dukungan Anthropic.
SDK Python dan TypeScript menyediakan ID permintaan sebagai properti _request_id pada objek respons tingkat teratas. SDK C#, Go, Java, dan PHP menyediakannya melalui accessor respons mentah masing-masing, sedangkan SDK Ruby menyediakannya melalui middleware. Di semua SDK kecuali Ruby, gunakan with_raw_response untuk membaca header respons lainnya, seperti anthropic-organization-id dan anthropic-workspace-id. Di Ruby, gunakan middleware yang sama. Di Claude Platform on AWS, gunakan juga accessor respons mentah untuk membaca ID permintaan AWS (x-amzn-requestid):
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")Untuk contoh ID permintaan Claude Platform on AWS dalam bahasa lain, lihat ID permintaan.
Permintaan panjang
Hindari menetapkan nilai max_tokens yang besar tanpa menggunakan Messages API dengan streaming
atau Message Batches APIPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali.:
- Beberapa jaringan mungkin memutus koneksi yang menganggur setelah periode waktu yang bervariasi, yang dapat menyebabkan permintaan gagal atau mengalami timeout tanpa menerima respons dari Anthropic.
- Keandalan jaringan berbeda-beda. Message Batches APIPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. dapat membantu Anda mengelola risiko masalah jaringan dengan memungkinkan Anda melakukan polling untuk hasil alih-alih memerlukan koneksi jaringan yang tidak terputus.
Jika Anda membangun integrasi API langsung, menetapkan TCP socket keep-alive dapat mengurangi dampak timeout koneksi idle pada beberapa jaringan.
Anthropic SDK memvalidasi bahwa permintaan Messages API non-streaming Anda tidak diperkirakan melebihi timeout 10 menit. SDK juga menetapkan opsi socket untuk TCP keep-alive.
Jika Anda tidak perlu memproses event secara bertahap, SDK dapat mengonsumsi stream untuk Anda dan mengembalikan objek Message lengkap, identik dengan yang dikembalikan oleh panggilan non-streaming:
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=128000,
messages=[{"role": "user", "content": "Write a detailed analysis..."}],
model="claude-sonnet-5",
) as stream:
message = stream.get_final_message()
print(next(block.text for block in message.content if block.type == "text"))Lihat Mendapatkan pesan akhir tanpa menangani peristiwa untuk detail lebih lanjut.
Error validasi umum
Prefill tidak didukung
Model Claude 4.6 dan yang lebih baru serta Claude Mythos Preview tidak mendukung “prefill” (pengisian awal) pesan asisten. Mengirim permintaan dengan pesan asisten terakhir yang di-prefill ke salah satu model ini akan mengembalikan 400 invalid_request_error:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "This model does not support assistant message prefill. The conversation must end with a user message."
}
}Gunakan output terstruktur pada model yang mendukungnya, instruksi prompt sistem, atau output_config.format sebagai gantinya.
Blok thinking tidak dapat dimodifikasi
Jika blok thinking dalam permintaan tidak cocok dengan yang dikembalikan oleh API, permintaan dapat mendapatkan 400 invalid_request_error. Pesan error dimulai dengan posisi blok yang bermasalah (misalnya, messages.1.content.0) dan berisi:
`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.Dengan “tool use” (penggunaan alat), kirim kembali setiap blok thinking dan redacted_thinking dari giliran asisten persis seperti yang diterima, termasuk blok yang field thinking-nya kosong. Jika aplikasi Anda menyaring blok konten berdasarkan tipe sebelum mengirim ulang, sertakan thinking dan redacted_thinking. Ini adalah kegagalan yang berbeda dari pemeriksaan prefiks, yang error-nya menyatakan bahwa sebuah blok terikat ke percakapan lain. Mengatur prefix_mismatch_behavior mungkin tidak mengatasinya. Lihat perbaikan untuk blok thinking yang dimodifikasi di Pemecahan masalah thinking.
Pemikiran diperpanjang tidak didukung
Model Claude 4.7 dan yang lebih baru tidak mendukung “extended thinking” (pemikiran diperpanjang). Mengirim thinking: {"type": "enabled"} ke salah satu model ini akan mengembalikan 400 invalid_request_error:
"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.Sebagai gantinya, gunakan pemikiran adaptif. Untuk pemetaan parameternya, lihat Migrasi ke pemikiran adaptif. Untuk memperbaiki error berdasarkan gejalanya, lihat Error 400 menyatakan "thinking.type.enabled" tidak didukung.
Pemikiran adaptif tidak didukung
Model yang hanya mendukung pemikiran diperpanjang (model Claude 4.5 dan yang lebih lama) menolak thinking: {"type": "adaptive"} dengan 400 invalid_request_error:
adaptive thinking is not supported on this modelGunakan thinking: {"type": "enabled", "budget_tokens": N} pada model-model ini; lihat Pemikiran diperpanjang untuk konfigurasinya dan perbaikan berbasis gejala untuk error pemikiran adaptif di Pemecahan masalah thinking.
Thinking tidak dapat dinonaktifkan
Pada Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, dan Claude Mythos Preview, thinking selalu aktif. Mengirim thinking: {"type": "disabled"} ke salah satu model ini akan mengembalikan 400 invalid_request_error. Pada semua model ini kecuali Claude Mythos Preview, pesannya berbunyi:
"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.Pada Claude Mythos Preview, satu-satunya model di antara model-model ini yang menerima pemikiran diperpanjang, pesannya berbunyi:
"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.Pada Claude Sonnet 5.5, thinking tidak dapat diatur ke disabled. Gunakan thinking: {"type": "between_tools"} untuk pengaturan thinking terendah, yang menonaktifkan thinking di awal. Mengirim thinking: {"type": "disabled"} akan mengembalikan 400 invalid_request_error dengan pesan ini:
To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.Pada effort xhigh atau max, permintaan dengan between_tools juga mengembalikan 400 invalid_request_error. Pesan error menyatakan bahwa thinking dinonaktifkan karena between_tools tidak memiliki thinking di awal:
output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.Dengan between_tools, effort tidak dapat berubah di tengah percakapan: output_config.effort per pesan yang berbeda dari level yang sedang berlaku akan mengembalikan error 400. Error tersebut menyebutkan posisi pesan yang menetapkan level baru:
messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.Claude Haiku 5.5 menerima thinking: {"type": "disabled"} dan menerapkan dua batas effort yang sama yang berlaku untuk between_tools: pada effort xhigh atau max, atau dengan output_config.effort per pesan yang berbeda dari level yang berlaku, permintaan akan mengembalikan error 400 invalid_request_error dengan pesan yang sesuai seperti yang ditunjukkan sebelumnya.
Dalam kedua pesan tersebut, “enable thinking” berarti pemikiran adaptif: hilangkan field thinking atau kirim thinking: {"type": "adaptive"}. Claude Sonnet 5.5 dan Claude Haiku 5.5 juga menolak "enabled" dengan error 400. Untuk memvariasikan effort di setiap giliran, gunakan pemikiran adaptif.
Mengirim thinking: {"type": "between_tools"} ke model apa pun selain Claude Sonnet 5.5 akan mengembalikan 400 invalid_request_error:
"thinking.type.between_tools" is not supported for this model.Untuk perbaikannya, lihat error between_tools dan effort di Pemecahan masalah thinking.
Hilangkan parameter thinking dan permintaan akan berjalan dengan pemikiran adaptif. Untuk menjaga konten thinking agar tidak muncul dalam respons tanpa menonaktifkan thinking, atur display: "omitted" pada konfigurasi thinking. Lihat perbaikan untuk error thinking yang dinonaktifkan di Pemecahan masalah thinking.
Penggunaan alat paksa tidak didukung
Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, dan Claude Mythos 5.1 tidak mendukung penggunaan alat paksa. Mengirim tool_choice: {"type": "any"} atau tool_choice: {"type": "tool", "name": "..."} ke salah satu model ini, termasuk pada endpoint penghitungan token, akan mengembalikan 400 invalid_request_error:
tool_choice: type "tool" and "any" are not supported for this model.tool_choice: {"type": "auto"} (default) dan {"type": "none"} diterima. Gunakan auto dengan penggunaan alat ketat untuk menjaga input alat tetap valid sesuai skema, atau output terstruktur ketika Anda membutuhkan respons itu sendiri dalam bentuk JSON yang tetap. Lihat Memaksa penggunaan alat.
Versi alat penggunaan komputer tidak didukung
Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, dan Claude Haiku 5.5 mengembalikan error 400 untuk versi alat penggunaan komputer apa pun yang tidak mereka terima. Di Claude API, itu termasuk computer_20251124 dengan header beta-nya. Model-model ini tidak menerima computer_20250124 di platform mana pun. Pesan invalid_request_error dari Claude API menyebutkan jenis yang ditolak dan, setelah Did you mean one of, mencantumkan jenis alat yang diterima model. Untuk Claude Opus 5.5, pesannya dimulai dengan:
'claude-opus-5-5' does not support tool types: computer_20251124.Claude API mengembalikan pesan yang sama untuk jenis alat yang didefinisikan Anthropic apa pun yang tidak didukung oleh model yang diminta. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, dan Claude Haiku 5.5 mendukung penggunaan komputer melalui toolset computer_toolset_20260801. Deklarasikan {"type": "computer_toolset_20260801"} tanpa header beta dan perbarui loop agen Anda seperti yang dijelaskan di Migrasi dari computer_20251124. Untuk beralih dari computer_20250124, lihat Pindahkan penggunaan komputer ke toolset di panduan migrasi Claude Haiku 5.5.
Di Amazon Bedrock, Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, dan Claude Haiku 5.5 juga menerima alat computer_20251124 dengan header beta computer-use-2025-11-24. Dengan InvokeModel API dari Amazon Bedrock, kirim computer-use-2025-11-24 dalam array anthropic_beta pada body permintaan alih-alih di header. Untuk API tersebut, lihat Claude di Amazon Bedrock (bedrock-runtime). Untuk model yang digunakan dengan setiap versi sebelumnya, lihat Versi alat sebelumnya.
Blok thinking yang terikat ke percakapan yang berbeda
Error 400 invalid_request_error ini berarti blok thinking yang Anda kirim kembali gagal dalam pemeriksaan prefiks. Bandingkan system, tools, dan pesan-pesan sebelum blok tersebut dengan yang Anda kirim ketika model menghasilkannya. Untuk mengetahui perubahan mana yang berpengaruh, lihat Apa yang dihitung sebagai perubahan. Pesan error diawali dengan posisi blok pertama yang gagal dalam pemeriksaan prefiks:
messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".Mengirim ulang riwayat yang sama akan gagal dengan cara yang sama. Memperbaiki kode yang melakukan pengeditan tidak membantu percakapan ini jika pengeditan tersebut masih ada dalam riwayatnya. Untuk melanjutkan, lakukan salah satu dari berikut ini:
- Kirim header beta
thinking-binding-controls-2026-08-01dan aturthinking.block_binding.prefix_mismatch_behaviorke"drop_block", pada percobaan ulang dan pada setiap permintaan berikutnya dalam percakapan tersebut. Pada Claude Sonnet 5.5 dan Claude Haiku 5.5,block_bindinghanya berfungsi denganthinking: {"type": "adaptive"}. - Hapus blok yang disebutkan oleh error tersebut serta setiap blok
thinkingdanredacted_thinkingsetelahnya, dalam pesan tersebut dan dalam setiap pesan berikutnya. Coba ulang, dan jangan sertakan blok yang dihapus dalam permintaan berikutnya.
Untuk mencegah percakapan baru gagal, pertahankan riwayat agar bersifat append-only (hanya ditambahkan). Lihat perbaikan untuk tanda tangan blok thinking yang tidak valid di Pemecahan masalah thinking.
Mengirim thinking.block_binding tanpa header beta thinking-binding-controls-2026-08-01 akan mengembalikan 400 invalid_request_error yang pesannya diakhiri dengan:
block_binding: Extra inputs are not permittedTambahkan header tersebut, aktifkan thinking, atau hapus field-nya.
Outbound web identity federation dinonaktifkan (Claude Platform on AWS)
Jika setiap permintaan ke Claude Platform on AWS mengembalikan "Outbound web identity federation is disabled for your account", jalankan aws iam enable-outbound-web-identity-federation satu kali untuk setiap akun AWS. Lihat Mengaktifkan outbound web identity federation untuk detailnya.
Langkah selanjutnya
Perbaikan berbasis gejala untuk error 400 konfigurasi thinking, blok thinking kosong, dan penghentian max_tokens.
Untuk mengurangi penyalahgunaan dan mengelola kapasitas pada API, terdapat batasan seberapa banyak suatu organisasi dapat menggunakan Claude API.
Stream respons Messages API secara bertahap dengan server-sent events, termasuk delta teks, penggunaan alat, dan pemikiran diperpanjang.
Apakah halaman ini membantu?