Error API Claude



Error HTTP

API mengikuti format kode error HTTP yang dapat diprediksi:

• 400 - invalid_request_error: Ada masalah dengan format atau konten permintaan Anda. Tipe error ini juga dapat digunakan untuk kode status 4XX lainnya yang tidak tercantum di bagian ini.

• 401 - authentication_error: Ada masalah dengan kunci API Anda (misalnya, formatnya salah, dicabut, atau kedaluwarsa; lihat Kedaluwarsa kunci). Pada Claude Platform di AWS, ini juga dapat menunjukkan masalah dengan kredensial AWS atau tanda tangan SigV4 Anda.

• 402 - billing_error: Ada masalah dengan informasi penagihan atau pembayaran Anda. Periksa detail pembayaran Anda di Claude Console, atau di AWS Marketplace jika Anda menggunakan Claude Platform di AWS.

• 403 - permission_error: Kunci API Anda tidak memiliki izin untuk menggunakan sumber daya yang ditentukan. Periksa pengaturan akses dan workspace organisasi Anda di Claude Console.

• 404 - not_found_error: Sumber daya yang diminta tidak ditemukan. Periksa jalur 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 lagi permintaannya.

• 413 - request_too_large: Permintaan melebihi jumlah byte maksimum yang diizinkan. Lihat Batas ukuran permintaan untuk maksimum per endpoint.

• 429 - rate_limit_error: Akun Anda telah mencapai batas laju (rate limit).

• 500 - api_error: Terjadi error tak terduga di dalam sistem internal Anthropic. Coba lagi permintaan dengan exponential backoff; jika error berlanjut, hubungi dukungan dengan menyertakan ID permintaan.

• 504 - timeout_error: Permintaan kehabisan waktu saat diproses. Pertimbangkan untuk menggunakan streaming Messages API 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 menghormati header retry-after jika ada. Setiap klien SDK menerima opsi maximum-retries untuk mengonfigurasi atau menonaktifkan perilaku ini.

Saat menerima respons streaming melalui server-sent events (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. Contohnya:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Sesuai dengan kebijakan versioning, nilai-nilai di dalam objek ini dapat bertambah, dan ada kemungkinan nilai type akan bertambah seiring waktu.



Tipe error SDK

SDK resmi memunculkan exception bertipe untuk error-error ini alih-alih mengembalikan JSON mentah, dan nama kelas serta namespace-nya berbeda menurut bahasa. Misalnya, 404 muncul sebagai anthropic.NotFoundError di Python, Anthropic::Errors::NotFoundError di Ruby, com.anthropic.errors.NotFoundException di Java, dan sebagai nilai tunggal *anthropic.Error (bercabang berdasarkan StatusCode) di Go. Tangkap kelas bertipe dari SDK alih-alih mencocokkan string pesan error, dengan menangani kelas yang paling spesifik terlebih dahulu. Setiap halaman SDK mendokumentasikan hierarki exception lengkapnya:

• 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. Pengidentifikasi yang sama muncul sebagai field request_id di badan respons error. Saat menghubungi dukungan tentang permintaan tertentu, sertakan ID ini untuk membantu menyelesaikan masalah Anda dengan cepat.

Pada Claude Platform di AWS, respons menyertakan dua ID permintaan: ID permintaan AWS (x-amzn-requestid, utama, terindeks di CloudTrail) dan ID permintaan Anthropic (request-id, sekunder). Gunakan ID permintaan AWS untuk pencarian di CloudTrail dan ID permintaan Anthropic untuk tiket dukungan Anthropic.

SDK Python dan TypeScript mengekspos ID permintaan sebagai properti _request_id pada objek respons tingkat atas. SDK C#, Go, Java, dan PHP mengeksposnya melalui accessor raw-response mereka, yang juga memungkinkan Anda membaca header respons lainnya. Pada Claude Platform di AWS, gunakan accessor raw-response untuk membaca ID permintaan AWS (x-amzn-requestid) juga:

Untuk contoh request-ID Claude Platform di AWS dalam bahasa lain, lihat ID Permintaan.



Permintaan panjang

Hindari menetapkan nilai max_tokens yang besar tanpa menggunakan streaming Messages API atau Message Batches API:

• Beberapa jaringan mungkin memutuskan koneksi yang idle setelah periode waktu yang bervariasi, yang dapat menyebabkan permintaan gagal atau kehabisan waktu 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 apa yang dikembalikan oleh panggilan non-streaming:

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 prefilling pesan assistant. Mengirim permintaan dengan pesan assistant terakhir yang sudah di-prefill ke salah satu model ini mengembalikan error 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."
  }
}

Sebagai gantinya, gunakan structured outputs pada model yang mendukungnya, instruksi prompt sistem, atau output_config.format.



Blok thinking tidak dapat dimodifikasi

Jika pesan assistant terbaru berisi blok thinking atau redacted_thinking yang diedit, diurutkan ulang, disaring, atau direkonstruksi sebelum dikirim kembali ke API, permintaan mengembalikan error 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 penggunaan alat (tool use), setiap blok thinking dan redacted_thinking dari giliran assistant 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 baik thinking maupun redacted_thinking. Lihat Pemecahan masalah thinking, Mempertahankan blok thinking, dan Output thinking pada Claude Fable 5 dan Claude Mythos 5.



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 mengembalikan error 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 parameter, dan Pemecahan masalah thinking membahas perbaikan berdasarkan gejala.



Adaptive thinking tidak didukung

Model yang hanya mendukung pemikiran diperpanjang (model Claude 4.5 dan yang lebih lama) menolak thinking: {"type": "adaptive"} dengan error 400 invalid_request_error:

adaptive thinking is not supported on this model

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



Thinking tidak dapat dinonaktifkan

Pada Claude Fable 5, Claude Mythos 5, dan Claude Mythos Preview, thinking selalu aktif. Mengirim thinking: {"type": "disabled"} ke salah satu model ini mengembalikan error 400 invalid_request_error:

"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 Fable 5 dan Claude Mythos 5, saran dari pesan error itu sendiri yaitu "thinking.type.enabled" juga ditolak. Hilangkan parameter thinking dan permintaan akan berjalan dengan adaptive thinking. Untuk menjaga konten thinking tidak muncul di respons tanpa mematikan thinking, tetapkan display: "omitted" pada konfigurasi thinking. Lihat Pemecahan masalah thinking.



Outbound web identity federation dinonaktifkan (Claude Platform di AWS)

Jika setiap permintaan ke Claude Platform di 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