Error Claude API



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 lain yang tidak tercantum di bagian ini.

• 401 - authentication_error: Ada masalah dengan "API key" (kunci API) Anda (misalnya, formatnya salah, dicabut, atau kedaluwarsa; lihat Kedaluwarsa kunci). Pada Claude Platform on 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 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 dalam 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 maksimum per endpoint.

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

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

• 504 - timeout_error: Permintaan mengalami timeout saat diproses. Pertimbangkan untuk menggunakan Messages API 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. 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. Misalnya:

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

Sesuai dengan kebijakan versioning, 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 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 satu nilai *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. 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 mengekspos ID permintaan sebagai properti _request_id pada objek respons tingkat atas. SDK C#, Go, Java, dan PHP mengeksposnya melalui accessor raw-response masing-masing, dan SDK Ruby melalui middleware. Mekanisme yang sama, bersama dengan with_raw_response di Python dan .withResponse() di TypeScript, juga dapat membaca header respons lainnya, seperti anthropic-organization-id dan anthropic-workspace-id. Pada Claude Platform on AWS, gunakan accessor raw-response untuk membaca ID permintaan AWS (x-amzn-requestid) juga:

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 streaming atau Message Batches API:

• Beberapa jaringan mungkin memutus koneksi idle setelah periode waktu yang bervariasi, yang dapat menyebabkan permintaan gagal atau timeout tanpa menerima respons dari Anthropic.
• Jaringan berbeda dalam hal keandalan. Message Batches API dapat membantu Anda mengelola risiko masalah jaringan dengan memungkinkan Anda melakukan polling 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 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."
  }
}

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



Blok thinking tidak dapat dimodifikasi

Jika pesan asisten terbaru berisi blok thinking atau redacted_thinking yang diedit, diurutkan ulang, difilter, 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 memfilter blok konten berdasarkan tipe sebelum mengirim ulang, sertakan thinking dan 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 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 parameter, 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 Extended thinking untuk konfigurasinya dan Pemecahan masalah thinking untuk perbaikan berbasis 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 akan mengembalikan 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 "thinking.type.enabled" dari pesan error itu sendiri juga ditolak. Hilangkan parameter thinking dan permintaan akan berjalan dengan adaptive thinking. Untuk menjaga konten thinking tidak muncul dalam respons tanpa menonaktifkan thinking, tetapkan display: "omitted" pada konfigurasi thinking. Lihat Pemecahan masalah thinking.



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