Strategi fallback AI API: membangun matriks kegagalan provider

Retry AI API, fallback route, dan substitusi model adalah tiga tindakan berbeda. Retry mengulang attempt dengan contract yang sama. Route fallback mengirim model dan protocol yang diminta ke jalur lain yang eligible. Model substitution mengubah model sehingga quality, price, latency, perilaku Tool, Context Limit, dan output format juga dapat berubah.

Policy yang andal menetapkan tindakan yang diizinkan sebelum incident. Keputusan harus mempertimbangkan Failure Class, fase response, Idempotency dari keseluruhan operasi, dan jumlah attempt yang masih muat dalam deadline pengguna.

Pisahkan retry, fallback, dan substitusi model

Gunakan nama berbeda dalam configuration, log, dan runbook.

Tindakan	Yang berubah	Tujuan yang tepat	Risiko utama
Same-route retry	Waktu dan Attempt Number	Pulih dari kegagalan sementara singkat pada route yang sama	Menambah beban ke dependency yang tidak sehat
Same-contract fallback	Upstream Channel, Account, atau Group berurutan	Menjaga model dan protocol saat satu jalur gagal	Incompatibility tersembunyi antar-route yang dianggap setara
Model substitution	Model ID atau Model Policy bernama	Trade-off quality, cost, atau availability yang disetujui produk	Perubahan perilaku dan Billing secara diam-diam

Jangan menyebut ketiganya “retry”. Operator perlu mengetahui apakah request diulang, dipindahkan, atau dijawab model lain. Bagi pengguna, Model Substitution harus menjadi Product Contract eksplisit, bukan recovery shortcut yang tidak terlihat.

Beberapa gateway mendukung urutan Provider atau Model Steps. Dokumentasi fallback Cloudflare, misalnya, menunjukkan Step yang berhasil. Prinsip pentingnya bukan menyalin policy vendor, melainkan mempertahankan Attempt-level Evidence setiap kali route berubah.

Terapkan empat gate sebelum replay

Status Code saja bukan Retry Policy. Periksa:

1. Failure Class: sementara, permanen, kesalahan caller, atau hasilnya ambigu?
2. Response Phase: terjadi sebelum Header, sebelum output efektif, atau sesudah output terkirim?
3. Idempotency: dapatkah seluruh operasi diulang tanpa Side Effect ganda?
4. Attempt Budget: apakah Wall-clock Time dan attempt yang tersedia masih cukup?

Retry Strategy Google Cloud membuat dua pembedaan dasar yang sama untuk API umum: response menunjukkan apakah retry mungkin berguna dan Idempotency menentukan keamanannya. 408, 429, 5xx, Socket Timeout, dan Disconnect sering bersifat sementara, tetapi operasi non-idempotent memerlukan syarat lebih ketat.

Dalam AI Workflow, Idempotency melampaui HTTP Request ke model. Prompt yang diputar ulang dapat mengusulkan email, refund, deploy, atau Database Write yang sama. Tool Execution memerlukan Idempotency Key stabil dan result yang disimpan, sekalipun Inference bersifat Read-only.

Mulai dari Failure Matrix

Matriks ini merupakan Application Policy konservatif. Gateway dapat melakukan Same-contract Channel Failover internal sebelum aplikasi menerima terminal result, jadi koordinasikan kedua layer.

Kegagalan atau fase	Same-route retry	Same-contract fallback	Berhenti atau investigasi	Alasan
Client Validation Error, Unsupported Field, Malformed Request	Tidak	Tidak	Perbaiki request	Contract invalid yang sama tidak akan berhasil saat diulang
Gateway Authentication, Authorization, Quota, Policy Denial	Tidak	Tidak	Perbaiki Account atau Policy	Provider Route lain tidak boleh melewati keputusan gateway
Upstream Credential/Account Failure sebelum output	Tidak pada route gagal	Ya, dengan Channel terverifikasi	Isolasi dan investigasi Channel	Contract tetap sama saat credential tidak sehat dikeluarkan
Network Failure atau 408 sebelum output	Maksimal satu attempt terbatas jika idempotent	Ya	Berhenti pada deadline	Mungkin sementara, tetapi hasil setelah Disconnect dapat ambigu
429 sebelum output	Retry tertunda mengikuti Retry-After	Ya, jika route setara punya capacity	Berhenti saat budget habis	Pengulangan langsung memperburuk Rate Limit
500, 502, 503, 504 sebelum output	Terbatas dengan Backoff	Ya	Investigasi kegagalan berulang	Biasanya sementara, tetapi bukan bukti semua route aman
Provider Response Schema-invalid sebelum downstream output	Biasanya tidak	Hanya ke route yang sudah diuji untuk Schema tersebut	Isolasi atau periksa Compatibility	Implementasi incompatibility jarang membaik dengan pengulangan
Model Refusal atau Policy-safe Completion	Tidak	Tidak	Kembalikan hasil	Refusal valid bukan kegagalan infrastruktur
Caller Cancellation atau downstream 499	Tidak	Tidak	Berhenti segera	Caller tidak lagi memerlukan pekerjaan
Partial Stream setelah visible content atau Tool Arguments	Tanpa replay transparan	Tanpa fallback transparan	Tandai Partial, aplikasi memutuskan	Stream kedua dapat menduplikasi atau bertentangan dengan output
Status Tool Side Effect tidak diketahui	Tidak sebelum Reconciliation	Tidak sebelum Reconciliation	Periksa Idempotency Record atau sistem target	Re-inference dapat mengusulkan Side Effect yang sama

503 sebelum output berbeda dari koneksi yang putus setelah 400 token terlihat.

Perlakukan awal stream sebagai Commit Boundary

Sebelum Downstream Output dimulai, gateway dapat membuang attempt gagal dan memilih route lain tanpa mengekspos dua jawaban. Setelah byte bermakna pertama, transparent replay menjadi tidak aman.

Memulai ulang stream dapat:

• mengulang awal jawaban;
• menghasilkan kelanjutan berbeda;
• mengirim Function Call ganda dengan Call ID baru;
• mengubah Usage dan Cost tanpa batas jelas;
• membuat Client tidak dapat memasangkan Event dengan Attempt.

Jika stream terputus setelah output, kembalikan Terminal Partial atau Transport Error dengan Request Identity asli. Aplikasi dapat menawarkan “coba lagi” secara eksplisit, melanjutkan dari checkpoint aman, atau membuang partial output. Jangan menyambung Model Stream baru ke stream lama seolah tidak ada kegagalan.

Untuk Function Calling, simpan Tool Call Identity dan Side-effect Result yang diterima sebelum retry dapat membuat ulang panggilan. Perbandingan Function Calling menjelaskan hubungan Call ID dan Application Idempotency.

Batasi backoff dengan attempt dan waktu total

Exponential Backoff menyebar attempts dalam waktu; Jitter mencegah banyak client mengulang serempak setelah outage bersama.

delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)

Ikuti Retry-After valid jika masih muat dalam deadline. Backoff bukan izin retry: Failure dan Idempotency Gate harus lolos lebih dahulu.

Tetapkan Total Budget, bukan hanya counter:

• maksimum attempts per User Action;
• maksimum Elapsed Time termasuk Queue dan Backoff;
• attempt sebelum dan sesudah memilih Fallback Group;
• waktu minimum untuk menghasilkan jawaban berguna;
• propagasi Caller Cancellation ke semua active attempts.

Untuk request interaktif ber-deadline 15 detik, tiga attempt masing-masing 10 detik bukan policy yang dapat dijalankan. Batch Workload dapat memakai budget lebih panjang, tetapi tetap membutuhkan Terminal Deadline dan Durable Job Identity.

Cegah Retry Amplification antar-layer

Jika SDK mencoba tiga kali, gateway menguji tiga route untuk setiap request, dan Upstream Proxy melakukan dua call per route:

3 client attempts × 3 gateway attempts × 2 upstream attempts = 18 provider calls

Satu User Action menjadi 18 Provider Calls. Saat outage, Queueing, Rate Limit, biaya, dan Recovery Time meningkat.

Bagikan Retry Ownership:

• gateway menangani Same-contract Channel Failover langsung;
• aplikasi memutuskan apakah seluruh User Action boleh diulang;
• SDK Automatic Retries dimatikan atau dibatasi jika gateway sudah mencoba;
• Async Jobs memakai satu Durable Job ID dan Attempt Ledger;
• tidak ada layer memulai attempt setelah Caller Cancellation.

Catat Attempt Number layer tersebut dan End-to-end Request ID stabil. Tanpanya, setiap komponen terlihat hanya mencoba dua atau tiga kali sementara amplifikasi total tersembunyi.

Verifikasi bahwa fallback menjaga contract

Model Name publik yang sama tidak membuktikan perilaku route yang sama. Sebelum menambah Channel ke Fallback Set transparan, minta bukti:

Area contract	Bukti yang dibutuhkan
Model Identity	Requested Model tersedia tanpa Silent Mapping
Endpoint	Request Responses atau Chat Completions diterima sesuai configuration
Streaming	Event Types, Termination, Usage, dan Cancellation bekerja
Structured Output	Subset JSON Schema dan Strict Behavior yang diperlukan bekerja
Function Calling	Tools, Call IDs, Argument Streaming, dan Results dapat Round-trip
Limits	Context, Output, Rate, dan Concurrency sesuai Workload
Errors	Status dan Error Bodies dapat diklasifikasi tanpa membocorkan Secrets
Usage and Cost	Tokens, Cache Fields, Service Tier, dan Price Policy dipahami
Safety and Region	Policy, Data Path, dan Residency tetap sesuai

Jika satu persyaratan gagal, route itu bukan fallback transparan untuk workload tersebut. Route masih dapat digunakan dalam Product Policy lain yang eksplisit.

Mengubah model selalu keputusan produk. Tetapkan model yang diizinkan, Quality Floor, Price Ceiling, Tool Contract, dan User-visible Disclosure. Jangan diam-diam memilih model lebih murah atau lemah hanya karena route error.

Pahami semantics fallback Modelflare

Modelflare mencari jalur eligible untuk model yang diminta API Client. API Key biasa memiliki Primary Group dan dapat memiliki Fallback Groups berurutan. Smart API Key mengevaluasi Groups yang tersedia sesuai Routing Strategy. Keduanya tidak boleh mengganti Requested Model secara diam-diam.

Group-level RPM Admission terjadi sebelum Billing dan Upstream Request. Jika Group penuh, Fallback Group berurutan atau Smart Routing Candidate dapat dievaluasi; tanpa Group eligible, request mengembalikan 429.

Di dalam Group, Channel Priority menentukan urutan Account Failover. Setelah Upstream Error, Channel gagal dikeluarkan dan seleksi berlanjut. Channel Failover saat ini independen dari RetryTimes dan AutomaticRetryStatusCodes; proses berhenti saat sukses, route habis, Caller Cancellation, atau Downstream Output sudah dimulai.

Same-model Path Decision internal ini bukan izin bagi Client membuat loop tanpa batas. Gunakan Reliable AI API Routing untuk desain Group dan Channel serta AI API Error Troubleshooting untuk membedakan Gateway Policy Error dan Upstream Failure.

Simpan evidence setiap attempt

200 akhir tidak membuktikan route pertama berhasil. Final Channel ID juga tidak menjelaskan attempts gagal. Simpan setidaknya:

• Request ID stabil dan Caller-visible Correlation ID;
• Attempt Sequence dan Group/Channel Reference;
• Model dan Endpoint Contract tiap attempt;
• Failure Status, Error Class, dan Stream Phase;
• apakah Downstream Output sudah dimulai;
• Timing Milestones dan Cancellation State;
• Input, Output, dan Cached-token Usage jika tersedia;
• Cost Attribution tiap attempt selesai atau billable;
• Terminal Reason: Success, Exhausted, Cancelled, Partial, atau Policy Stop.

Jangan menyimpan API Keys, Raw Prompts, Raw Responses, atau Provider Credentials hanya untuk diagnosis fallback. Redacted Error Classes dan Timing Metadata biasanya cukup; Request Archives harus dibatasi, berumur pendek, dan diaktifkan secara eksplisit.

Latih policy sebelum production traffic

Gunakan Protocol Boundary sebenarnya dengan input aman dan deterministik:

1. nonaktifkan Primary Channel sebelum Headers dan cek Same-model Path berikutnya;
2. kembalikan Rate Limit dan verifikasi Attempt Limits serta Retry-After;
3. batalkan Caller dan buktikan tidak ada attempt baru;
4. putuskan stream setelah output dan cegah transparent replay;
5. kirim Invalid Request dan pastikan fallback tidak menyembunyikannya;
6. ulangi Tool Workflow dan buktikan hanya satu Side Effect;
7. habiskan semua route dan verifikasi satu Terminal Error jelas;
8. periksa Attempt Ledger lalu rekonsiliasi Usage dan Cost.

Terapkan lebih dulu pada workload kecil. Pantau Attempt Count, Success-after-fallback, dan Raw Success Rate secara terpisah serta sediakan cara cepat menghapus route tidak sehat. Tujuannya bukan memaksimalkan fallback, melainkan pulih dengan aman dalam deadline terbatas sambil menjaga contract model dan evidence setiap attempt.