Error



Error HTTP

API mengikuti format kode error HTTP yang dapat diprediksi:

• 400 - invalid_request_error: Ada masalah dengan format atau konten permintaan Anda. Jenis 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. Pada Claude Platform di AWS, ini juga dapat mengindikasikan 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.

• 404 - not_found_error: Sumber daya yang diminta tidak ditemukan.

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

• 429 - rate_limit_error: Akun Anda telah mencapai batas laju.

• 500 - api_error: Terjadi error tak terduga di dalam sistem Anthropic.

• 504 - timeout_error: Permintaan mengalami timeout saat diproses. Pertimbangkan untuk menggunakan streaming untuk permintaan yang berjalan lama.

• 529 - overloaded_error: API sedang mengalami kelebihan beban sementara.

  

  Error 529 dapat terjadi ketika API mengalami lalu lintas tinggi di seluruh pengguna.

  Dalam kasus yang jarang terjadi, jika organisasi Anda mengalami peningkatan penggunaan yang tajam, Anda mungkin melihat error 429 karena batas akselerasi pada API. Untuk menghindari batas akselerasi, tingkatkan lalu lintas Anda secara bertahap dan pertahankan pola penggunaan yang konsisten.

Saat menerima respons streaming melalui SSE, ada kemungkinan error terjadi setelah respons 200 dikembalikan, yang dalam hal ini penanganan error tidak akan mengikuti mekanisme standar ini.



Batas ukuran permintaan

API menerapkan batas ukuran permintaan untuk memastikan kinerja yang optimal:

Jika Anda melebihi batas ini, Anda akan menerima error 413 request_too_large. Pada Claude API langsung, error ini dikembalikan dari Cloudflare sebelum permintaan mencapai server API.



Bentuk error

Error selalu dikembalikan 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. Sebagai contoh:

{
  "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 dalam objek ini dapat diperluas, dan ada kemungkinan nilai type akan bertambah seiring waktu.



Jenis error SDK

SDK resmi memunculkan exception bertipe untuk error ini alih-alih mengembalikan JSON mentah, dan nama kelas serta namespace berbeda menurut bahasa. Sebagai contoh, error 404 muncul sebagai anthropic.NotFoundError di Python, Anthropic::Errors::NotFoundError di Ruby, com.anthropic.errors.NotFoundException di Java, dan sebagai satu nilai *anthropic.Error (lakukan percabangan pada 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



Request ID

Setiap respons API menyertakan header request-id yang unik. Header ini berisi nilai seperti req_018EeWyXxfu5pfWkrYcMdjWG. Saat menghubungi dukungan tentang permintaan tertentu, sertakan ID ini untuk membantu menyelesaikan masalah Anda dengan cepat.

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

SDK resmi menyediakan Anthropic request ID sebagai properti pada objek respons tingkat atas, yang berisi nilai dari header request-id. Pada Claude Platform di AWS, gunakan accessor raw-response untuk juga membaca AWS request ID dari header HTTP:

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

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



Permintaan yang berjalan lama

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

• Beberapa jaringan mungkin memutus koneksi yang tidak aktif 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, Anda harus mengetahui bahwa menetapkan TCP socket keep-alive dapat mengurangi dampak timeout koneksi yang tidak aktif pada beberapa jaringan.

SDK memvalidasi bahwa permintaan Messages API non-streaming Anda tidak diperkirakan melebihi timeout 10 menit dan juga akan menetapkan opsi socket untuk TCP keep-alive.

Jika Anda tidak perlu memproses event secara inkremental, gunakan .stream() dengan .get_final_message() (Python) atau .finalMessage() (TypeScript) untuk mendapatkan objek Message lengkap tanpa menulis kode penanganan event:

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-4-8",
) as stream:
    message = stream.get_final_message()
print(message.content)

Lihat Streaming Messages untuk detail lebih lanjut.



Error validasi umum



Prefill tidak didukung

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, dan Claude Sonnet 4.6 tidak mendukung prefilling pesan assistant. Mengirim permintaan dengan pesan assistant terakhir yang telah diisi sebelumnya ke salah satu model ini akan mengembalikan 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Prefilling assistant messages is not supported for this model."
  }
}

Gunakan structured outputs pada model yang mendukungnya, instruksi prompt sistem, atau output_config.format sebagai gantinya.



Blok thinking tidak dapat dimodifikasi

Jika pesan assistant terbaru berisi blok thinking atau redacted_thinking yang telah 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 penggunaan alat, 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 memfilter blok konten berdasarkan tipe sebelum mengirim ulang, sertakan baik thinking maupun redacted_thinking. Lihat Mempertahankan blok thinking dan Output thinking pada Claude Fable 5 dan Claude Mythos 5.



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 satu kali per akun AWS. Lihat Mengaktifkan outbound web identity federation untuk detailnya.