API Error 529 "Overloaded": Strategi Retry, Backoff, dan Fallback

Jika log produksi Anda menampilkan 529 overloaded_error, penyedia sedang memberi tahu bahwa API untuk sementara kelebihan beban. Dalam dokumentasi Claude API milik Anthropic, 529 - overloaded_error berarti "API untuk sementara kelebihan beban," dan dokumentasi tersebut mencatat bahwa error 529 dapat terjadi saat lalu lintas tinggi di antara semua pengguna.

Itu membuat API Error 529 "Overloaded": Strategi Retry, Backoff, dan Fallback berbeda dari permintaan yang salah format, API key yang tidak valid, atau masalah kuota biasa. Respons pertama seharusnya bukan "ubah prompt" atau "beli kuota lebih banyak." Respons pertama harus berupa playbook keandalan yang terkontrol: klasifikasikan kegagalan, lakukan retry hanya dalam batas anggaran, lindungi pengguna dari retry storm, dan tentukan kapan jalur fallback lebih aman daripada menunggu.

Panduan ini ditulis untuk tim produk AI dan platform yang menjalankan beban kerja LLM, agent, atau multimodal di produksi. Panduan ini memberi Anda matriks aksi error yang praktis, anggaran retry, pola backoff, dan alur keputusan fallback yang dapat Anda salin ke dalam runbook insiden.

Jawaban Singkat

Untuk API Error 529 "Overloaded": Strategi Retry, Backoff, dan Fallback, gunakan kebijakan default berikut:

1. Anggap 529 overloaded_error sebagai sinyal kapasitas provider yang bersifat sementara, bukan bug validasi klien.
2. Lakukan retry pada request idempotent atau read-only dengan exponential backoff dan jitter.
3. Patuhi retry-after saat provider mengirimkannya.
4. Berhenti setelah anggaran retry kecil, biasanya dua atau tiga percobaan untuk traffic interaktif.
5. Jangan melakukan retry secara membabi buta untuk panggilan tool non-idempotent, tindakan tulis, pembelian, email, atau apa pun yang mungkin menimbulkan side effect.
6. Buka circuit breaker ketika 529 mengelompok berdasarkan provider, model, endpoint, atau region.
7. Lakukan fallback hanya ketika model alternatif dapat memenuhi kontrak produk yang sama.
8. Catat request-id, model, route, jumlah retry, hasil akhir, dan dampak yang terlihat oleh pengguna.

Dengan kata lain: retry sebentar, perlambat antrean, lakukan failover saat equivalence dapat diterima, dan berhenti ketika request tidak lagi aman untuk diulang.

Mengapa API Error 529 Overloaded Terjadi

529 overloaded_error adalah kondisi kapasitas. Biasanya ini berarti request Anda sudah mencapai provider, tetapi sisi provider terlalu sibuk untuk melayaninya saat itu. Anthropic mendokumentasikan ini secara terpisah dari 429 rate_limit_error. Perbedaan itu penting:

529 dapat muncul selama lonjakan trafik di seluruh penyedia, bahkan jika beban kerja Anda sendiri tidak melakukan hal yang tidak biasa. Namun, jika Anda meluncurkan fitur baru, menjalankan batch, atau mengirim swarm agen secara tiba-tiba, Anda juga harus memeriksa apakah peningkatan trafik Anda menyebabkan tekanan lokal atau perilaku batas akselerasi.

Matriks Error-Tindakan

Gunakan matriks ini sebelum mengubah kode dalam keadaan panik.

Inilah bagian yang paling sering dilewatkan halaman error generik: model yang overloaded bukan sekadar status HTTP. Ini adalah keputusan produk tentang pekerjaan duplikat, latensi, kualitas output, dan kepercayaan pengguna.

Kebijakan Retry yang Aman untuk 529

Mulailah dengan budget retry terpisah untuk beban kerja interaktif dan latar belakang.

Bentuk retry paling sederhana adalah exponential backoff dengan jitter:

function backoffMs(attempt: number) {
  const base = 250;
  const cap = 8_000;
  const exponential = Math.min(cap, base * 2 ** attempt);
  const jitter = Math.floor(Math.random() * exponential * 0.4);
  return exponential + jitter;
}

Gunakan nilai kecil untuk produk interaktif. Pesan chat yang mencoba ulang selama 60 detik mungkin secara teknis tangguh, tetapi tetap terasa rusak bagi pengguna. Untuk antrean latar belakang, gunakan jendela backoff yang lebih lebar dan simpan work item untuk diproses nanti alih-alih membombardir penyedia.

Hormati Retry-After, Tetapi Jangan Bergantung Padanya

Beberapa API mengirim header retry-after untuk batas laju atau kegagalan sementara. Dokumentasi Anthropic mengatakan SDK resmi melakukan retry atas kegagalan sementara dengan exponential backoff, dua kali secara default, dan menghormati retry-after ketika ada. Controller Anda sendiri harus melakukan hal yang sama saat Anda melewati atau membungkus SDK.

Tetapi jangan membangun kebijakan yang hanya bekerja ketika retry-after ada. Respons 529 mungkin tidak selalu disertai waktu tunggu yang berguna. Controller fallback Anda tetap membutuhkan:

• nilai maksimum percobaan,
• batas maksimum waktu nyata (wall-clock),
• circuit breaker per rute,
• batas usia antrean,
• dan mode kegagalan akhir yang terlihat oleh pengguna.

Hindari Retry Storm

Respons terburuk terhadap overload penyedia adalah traffic retry yang tersinkronisasi. Jika setiap worker langsung mencoba ulang, Anda mengubah satu insiden pada penyedia menjadi insiden yang lebih besar.

Tambahkan kontrol berikut:

Panduan retry-with-backoff dari AWS menyampaikan poin operasional yang sama: retry membantu kegagalan sementara, tetapi terlalu banyak retry dapat meningkatkan kontensi dan degradasi layanan.

Kapan Harus Fallback Alih-alih Retry

Fallback tidak sama dengan retry. Retry meminta rute yang sama untuk mencoba lagi. Fallback mengubah rute, penyedia, model, region, atau kapabilitas.

Gunakan fallback ketika keempat kondisi berikut benar:

1. Rute utama gagal berulang kali dengan 529 atau error sementara terkait.
2. Pengguna atau beban kerja masih mendapat manfaat dari respons setelah latensi tambahan.
3. Rute alternatif memenuhi kontrak produk yang sama.
4. Permintaan belum menghasilkan output parsial atau efek samping yang tidak pasti.

Gunakan kontrak rute seperti ini:

task: support_reply_draft
primary:
  model: claude-sonnet-current
  max_attempts: 2
  retry_on: [529, 500, 502, 503, 504, timeout]
  backoff: exponential_jitter
fallback:
  model: approved-general-chat-model
  allowed_when:
    - no_partial_stream_output
    - no_write_side_tool_executed
    - response_schema_compatible
    - latency_budget_remaining_ms > 3000
stop:
  user_message: "The model is overloaded. Please retry in a moment."
log:
  fields:
    - request_id
    - route
    - model
    - retry_count
    - fallback_used
    - final_status

Jika produk Anda bergantung pada perilaku model yang tepat, format tool-call, kebijakan sitasi, perilaku keamanan, atau fitur konteks panjang, fallback lintas model bisa lebih buruk daripada kegagalan yang jelas. Untuk beban kerja seperti itu, fallback ke provider/model yang sama di rute lain lebih aman daripada fallback ke keluarga model yang berbeda.

Untuk arsitektur yang lebih luas di balik keputusan ini, pasangkan halaman error ini dengan LLM API fallback routing production playbook dari Flatkey dan model fallback strategy workflow playbook. Panduan-panduan tersebut membahas pola controller yang lebih besar; halaman ini tetap berfokus pada respons overloaded 529.

Aturan Idempotency untuk 529

Keamanan retry bergantung pada idempotency. Panduan AWS menekankan bahwa operasi harus idempotent ketika Anda melakukan retry dengan backoff; jika tidak, update parsial dapat merusak state. Panduan error level rendah Stripe menyampaikan hal yang sama untuk error jaringan dan server: request yang gagal atau tidak jelas dapat membuat klien tidak yakin apakah server menerima atau menjalankan request tersebut.

Untuk produk AI, terapkan aturan itu pada tools dan side effect:

Aturan praktisnya sederhana: jika request yang diulang dapat menciptakan state eksternal duplikat, jangan biarkan generic retry wrapper mengambil alih.

Ambang Batas Circuit Breaker

Circuit breaker mengubah overload berulang menjadi keputusan rute sementara. Anda tidak perlu sistem yang rumit untuk memulainya.

Gunakan kebijakan seperti:

• Buka circuit ketika 529 melebihi 20% dari percobaan untuk suatu rute selama dua menit dan setidaknya 20 request telah dicoba.
• Biarkan circuit tetap terbuka selama 60-180 detik untuk traffic interaktif.
• Kirim sejumlah kecil probe request sebelum menutup circuit.
• Reset secara perlahan; jangan mengirim seluruh antrean kembali ke rute sekaligus.
• Lacak state circuit berdasarkan provider, model, endpoint family, dan region jika memungkinkan.

Circuit breaker sangat penting untuk sistem agen karena agen sering melakukan retry di beberapa layer: model SDK, orchestration library, job worker, dan user command loop. Hitung setiap layer atau Anda bisa tanpa sengaja melipatgandakan retry budget Anda.

Checklist Observability

Untuk setiap insiden 529, log bukti yang cukup untuk menjawab empat pertanyaan: apa yang gagal, mengapa di-retry, apakah fallback terjadi, dan apa yang dilihat pengguna.

Tim Flatkey dapat menggunakan pola yang sama dengan https://router.flatkey.ai/v1: rute melalui satu base URL yang kompatibel dengan OpenAI, tetap eksplisit dalam pemilihan model, dan tinjau log penggunaan setelah insiden. Quickstart Flatkey mendokumentasikan shared key, katalog model, router base URL, dan Usage Logs sebagai tempat untuk memverifikasi lalu lintas permintaan dan biaya.

Jika Anda masih memisahkan penanganan rate-limit dari penanganan overload, gunakan panduan batas rate LLM untuk kebijakan 429/RPM/TPM dan panduan metrik API routing AI untuk pelaporan keandalan.

Bagaimana Flatkey Cocok dengan Rencana Pemulihan 529

Flatkey seharusnya tidak diperlakukan sebagai cara untuk berpura-pura bahwa overload tidak bisa terjadi. Provider model di hulu tetap bisa sibuk. Peran yang berguna bagi gateway adalah kontrol operasional:

• Satu base URL yang kompatibel dengan OpenAI untuk lalu lintas model.
• Katalog model bersama untuk kandidat fallback yang disetujui.
• Satu catatan penggunaan dan biaya untuk retry dan kegagalan yang pulih.
• Perubahan kebijakan routing yang lebih cepat tanpa menulis ulang setiap klien aplikasi.
• Jejak audit yang lebih bersih saat tim produk, platform, dan keuangan meninjau insiden.

Bagi tim produksi, ini sering kali lebih berharga daripada loop retry yang lebih besar. Loop retry yang lebih besar dapat menyembunyikan insiden sampai menjadi mahal. Kebijakan yang dirutekan membuat overload terlihat dan terkendali.

Runbook Produksi untuk API Error 529

Salin ini ke proses insiden Anda:

1. Konfirmasi kelas error: 529 overloaded_error, provider, model, endpoint, timestamp, dan request ID.
2. Periksa apakah request bersifat read-only, streaming, atau write-side.
3. Terapkan retry budget pada rute dengan exponential backoff dan jitter.
4. Hentikan retry jika request menghasilkan output parsial atau efek samping yang tidak pasti.
5. Buka circuit breaker jika 529 menumpuk pada rute provider/model yang sama.
6. Fallback hanya ke rute yang disetujui dengan perilaku output, keamanan, latensi, dan biaya yang kompatibel.
7. Tampilkan pesan yang terlihat oleh pengguna saat budget latensi habis.
8. Tinjau jumlah retry, jumlah fallback, request yang berhasil dipulihkan, request yang gagal, dan bukti pencegahan duplikasi setelah insiden.

FAQ

Apakah API Error 529 sama dengan 429?

Tidak. Dalam dokumentasi Anthropic, 529 berarti API untuk sementara mengalami overload, sedangkan 429 adalah error rate-limit. Perlakukan 529 sebagai overload provider dan 429 sebagai masalah rate/quota/traffic shape sampai log Anda membuktikan sebaliknya.

Haruskah saya me-retry API Error 529?

Ya, tetapi hanya dalam batas budget dan hanya ketika request aman untuk diulangi. Gunakan exponential backoff dengan jitter, patuhi retry-after jika ada, dan hentikan ketika output parsial atau side effect eksternal membuat replay tidak aman.

Berapa banyak retry yang harus saya gunakan untuk error 529 overloaded?

Untuk fitur AI interaktif, mulai dengan dua retry dan deadline wall-clock yang ketat. Job latar belakang dapat menggunakan retry lebih banyak, tetapi harus memakai batas usia antrean, penanganan dead-letter, dan circuit breaker.

Haruskah saya otomatis beralih model setelah 529?

Hanya jika model fallback dapat memenuhi kontrak produk yang sama. Jika perilaku spesifik model, tools, skema, kebijakan keamanan, atau panjang konteks penting, fallback mungkin memerlukan tindakan yang terlihat oleh manusia seperti "regenerate dengan model lain" alih-alih perpindahan transparan.

Apa yang harus saya tampilkan kepada pengguna selama insiden 529?

Gunakan bahasa status sementara yang sederhana: "Model sedang overload. Kami sedang mencoba lagi sebentar." Jika retry budget habis, tawarkan tombol retry atau alternatif yang terdegradasi. Jangan tampilkan detail internal provider kecuali pengguna Anda adalah developer yang membutuhkan detail tersebut.

Rekomendasi Akhir

Rencana API Error 529 "Overloaded": Retry, Backoff, and Fallback Strategies yang paling aman bukanlah satu loop while retry. Ini adalah kebijakan rute: retry overload sementara sebentar, lakukan backoff dengan jitter, lindungi pekerjaan non-idempotent, aktifkan circuit breaker untuk kegagalan berulang, dan fallback hanya ketika rute alternatif mempertahankan kontrak pengguna.

Jika tim Anda sudah menjalankan lebih dari satu model atau provider, letakkan kebijakan itu di balik satu gateway. Dengan Flatkey, Anda dapat mengarahkan klien yang kompatibel dengan OpenAI ke https://router.flatkey.ai/v1, menyimpan kandidat fallback dalam satu katalog model, dan meninjau kegagalan yang berhasil dipulihkan di Usage Logs setelah peluncuran.

Mulailah dengan Flatkey API quickstart jika Anda memerlukan alur panggilan pertama, atau bandingkan pilihan routing di level workload dalam Claude API proxy vs multi-model router.

Sumber yang Diperiksa

• Error API Anthropic Claude: https://platform.claude.com/docs/en/api/errors
• AWS Prescriptive Guidance, pola retry with backoff: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/retry-backoff.html
• Penanganan error lanjutan dan idempotensi Stripe: https://docs.stripe.com/error-low-level
• Indeks dokumentasi Flatkey: https://docs.flatkey.ai/index.md
• Quickstart Flatkey: https://docs.flatkey.ai/quickstart.md
• Ikhtisar produk Flatkey: /Users/solveainc/.11agents/flatkey/knowledge_base/information/what-we-do/product-overview.md
• Strategi pemasaran Flatkey: /Users/solveainc/.11agents/flatkey/knowledge_base/marketing/strategy.md