Error Claude API

Error HTTP

API mengikuti format kode error HTTP yang dapat diprediksi:

• 400 - invalid_request_error: Terdapat masalah pada format atau konten permintaan Anda. Tipe error ini juga dapat digunakan 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, kecuali batas pada workspace Claude Code, yang dapat mengembalikan 429 sebagai gantinya.

• 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.

• 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 header retry-after dan akan terus gagal hingga akses dipulihkan; lihat Mencapai batas pengeluaran Anda untuk cara mengenalinya.

• 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.

• 504 - timeout_error: Permintaan mengalami timeout saat diproses. Pertimbangkan untuk menggunakan Messages API dengan streaming untuk permintaan yang berjalan lama. 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

API memberlakukan batas ukuran permintaan:

Jika Anda melebihi batas ini, Anda akan menerima error 413 request_too_large. Pada Claude API langsung, 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"
}

Sesuai dengan kebijakan pembuatan versi, nilai dalam objek-objek ini dapat bertambah, dan nilai type mungkin akan berkembang seiring waktu.

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:

• Python · TypeScript · C# · Go · Java · PHP · Ruby

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 API:

• Beberapa jaringan mungkin memutus koneksi yang idle setelah periode waktu yang bervariasi, yang dapat menyebabkan permintaan gagal atau mengalami timeout tanpa menerima respons dari Anthropic.
• Keandalan jaringan berbeda-beda. Message Batches API 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.

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 Streaming Messages 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 structured outputs pada model yang mendukungnya, instruksi prompt sistem, atau output_config.format sebagai gantinya.

Blok thinking tidak dapat dimodifikasi

Jika pesan asisten terbaru berisi blok thinking atau redacted_thinking yang diedit, diurutkan ulang, disaring, atau direkonstruksi sebelum dikirim kembali ke API, permintaan akan mengembalikan 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), setiap blok thinking dan redacted_thinking dari giliran asisten harus dikirim kembali persis seperti yang diterima, termasuk blok yang field thinking-nya kosong. Kirim kembali blok thinking tanpa perubahan, dan jika aplikasi Anda menyaring blok konten berdasarkan tipe sebelum mengirim ulang, sertakan thinking maupun redacted_thinking. Lihat Pemecahan masalah thinking, Mempertahankan blok thinking, dan Thinking yang dipertahankan.

Extended thinking tidak didukung

Model Claude 4.7 dan yang lebih baru telah menghapus "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 adaptive thinking. Migrasi ke adaptive thinking menunjukkan pemetaan parameternya, dan Pemecahan masalah thinking membahas perbaikan berbasis gejala.

Adaptive thinking 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 model

Gunakan thinking: {"type": "enabled", "budget_tokens": N} pada model-model ini; lihat Pemikiran diperpanjang untuk konfigurasinya dan Pemecahan masalah thinking untuk perbaikan berbasis gejala.

Thinking tidak dapat dinonaktifkan

Pada 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. Pesannya 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 menolak "enabled" dengan error 400. Untuk memvariasikan effort per 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 Pemecahan masalah thinking, yang membahas error between_tools dan effort.

Hilangkan parameter thinking dan permintaan akan berjalan dengan pemikiran adaptif. Untuk menjaga konten thinking agar tidak muncul di respons tanpa menonaktifkan thinking, atur display: "omitted" pada konfigurasi thinking. Lihat Pemecahan masalah thinking.

Penggunaan alat paksa tidak didukung

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 strict tool use untuk menjaga input alat tetap valid sesuai skema, atau structured outputs ketika Anda membutuhkan respons itu sendiri dalam bentuk JSON yang tetap. Lihat Memaksa penggunaan alat.

Versi alat computer use tidak didukung

Di Claude API dan Google Cloud, Claude Opus 5.5, Claude Sonnet 5.5, dan Claude Haiku 5.5 mendukung computer use hanya sebagai toolset computer_toolset_20260801. Di platform tersebut, mengirim entri tools bertipe computer_20251124 yang lebih lama (dengan header beta alat tersebut) ke salah satu model ini akan mengembalikan 400 invalid_request_error. Pesannya menyebutkan tipe yang ditolak, lalu mencantumkan tipe alat yang diterima model setelah Did you mean one of. Untuk Claude Opus 5.5, pesannya diawali dengan:

'claude-opus-5-5' does not support tool types: computer_20251124.

API mengembalikan pesan yang sama untuk tipe alat apa pun yang didefinisikan Anthropic yang tidak didukung oleh model yang diminta. Deklarasikan {"type": "computer_toolset_20260801"} tanpa header beta dan perbarui loop agen Anda seperti yang dijelaskan di Migrasi dari computer_20251124. Model-model sebelumnya yang mendukung toolset tetap menerima computer_20251124, begitu pula Claude Opus 5.5 dan Claude Sonnet 5.5 di Amazon Bedrock.

Blok thinking tidak lagi cocok dengan percakapan

Pada Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, dan Claude Haiku 5.5, API menerima blok thinking yang diputar ulang hanya selama prompt system, tools, dan pesan-pesan yang mendahuluinya tidak berubah. Untuk akun baru yang dibuat pada atau setelah 31 Agustus 2026, dan untuk permintaan apa pun yang mengatur thinking.block_binding.prefix_mismatch_behavior ke "error", blok yang diputar ulang dengan riwayat sebelumnya yang telah berubah akan ditolak dengan 400 invalid_request_error (dengan "drop_block", API membuang blok tersebut dan permintaan berhasil). Pesannya diawali dengan posisi blok pertama yang gagal:

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".

Tanpa header beta thinking-binding-controls-2026-08-01, pesan tersebut juga menyebutkan header itu. Pertahankan riwayat percakapan agar hanya ditambahkan (append-only), atau kirim header beta dengan prefix_mismatch_behavior: "drop_block" untuk membuang blok dan melanjutkan. Pada Claude Sonnet 5.5, block_binding hanya berfungsi dengan thinking: {"type": "adaptive"}. Dengan between_tools, pertahankan riwayat agar append-only, atau hapus blok thinking mulai dari giliran yang diedit dan seterusnya. Blok dari model yang tidak dapat dibaca oleh model target akan dibuang alih-alih ditolak. Lihat Menjaga prefix tetap tidak berubah dan 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 permitted

Tambahkan header tersebut, 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 sekali per akun AWS. Lihat Mengaktifkan outbound web identity federation untuk detailnya.

Langkah selanjutnya