Taksonomi Error LLM Gateway: Pisahkan Kegagalan Auth, Kuota, Provider, dan Safety

Taksonomi error LLM gateway adalah pembeda antara insiden yang terkendali dan badai retry yang mahal. Sebuah gateway tidak seharusnya memperlakukan setiap panggilan model yang gagal sebagai jenis error provider yang sama. Kredensial yang tidak valid, kuota yang habis, overload provider, request yang salah format, penolakan safety, timeout, dan cancel dari client semuanya memerlukan jalur pemulihan yang berbeda.

Kesalahan umum adalah mengirim setiap kegagalan ke dalam loop retry dan fallback yang sama. Itu bisa menyembunyikan key yang dicabut, menghabiskan batas belanja, merutekan konten yang tidak aman ke provider lain, atau menggandakan pekerjaan setelah respons streaming sudah mulai. Taksonomi error LLM gateway yang praktis memberi tim engineering, product, dan finance satu bahasa bersama untuk menjelaskan apa yang terjadi dan apa yang harus dilakukan gateway selanjutnya.

Flatkey cocok dengan model operasional ini karena situs publiknya saat ini memposisikan produk sebagai satu permukaan gateway untuk akses model, routing, billing, analitik penggunaan, dan kontrol operasional. Gunakan permukaan bersama itu untuk mengklasifikasikan kegagalan sebelum memilih perilaku retry, antre, fallback, atau fail-closed.

Taksonomi error LLM gateway dalam satu tabel

Mulailah dari kelasnya, bukan hanya status HTTP. Keluarga status yang sama bisa berarti hal yang berbeda di berbagai provider, SDK, dan bentuk endpoint.

Taksonomi error LLM gateway ini sengaja berorientasi pada tindakan. Ini bukan hanya memberi label error untuk dashboard. Ini memutuskan kapan sistem boleh menghabiskan lebih banyak token, kapan harus meminta pemilik untuk memperbaiki state, dan kapan harus berhenti.

Klasifikasikan sebelum melakukan retry

Dokumentasi resmi provider mendukung pemisahan kelas-kelas ini. Panduan error OpenAI membedakan autentikasi tidak valid, API key yang salah, kegagalan allowlist IP, rate limit, kuota atau billing yang habis, error server, overload, error koneksi SDK, timeout SDK, request yang salah format, penolakan permission, dan pengecualian rate-limit. Panduan rate limit-nya merekomendasikan exponential backoff acak tetapi juga mencatat bahwa request yang gagal tetap dihitung terhadap batas per menit.

Dokumentasi error Anthropic memisahkan invalid_request_error, authentication_error, permission_error, not_found_error, request_too_large, rate_limit_error, api_error, dan overloaded_error. Anthropic juga mendokumentasikan rate limit 429 dengan panduan retry-after, dan panduan stop-reason mereka mencantumkan refusal sebagai kondisi berhenti di level model.

Troubleshooting Gemini memetakan kegagalan autentikasi dan permission secara terpisah dari 429 RESOURCE_EXHAUSTED, error internal 500, dan ketidaktersediaan 503. Dokumentasi rate limit Gemini menjelaskan dimensi request, token, request harian, dan spend. Pengaturan safety Gemini juga menampilkan prompt block, finishReason kandidat, dan safetyRatings, termasuk finishReason SAFETY saat konten respons diblokir.

Bukti itu mengarah pada aturan sederhana: taksonomi error LLM gateway harus menormalisasi sinyal spesifik provider menjadi field keputusan sebelum gateway memilih tindakan.

Kegagalan Auth dan permission

Kegagalan auth dan permission harus segera dihentikan. Mencoba ulang key yang salah atau project yang dilarang biasanya hanya menambah noise tanpa mengubah hasil.

Normalisasikan sinyal-sinyal ini ke dalam kelas auth:

Dalam gateway, error auth harus mencakup owner_key, credential_id, project_id, provider, endpoint_family, requested_model, dan route_id. Hindari mencatat secret mentah. Insiden harus menjawab key mana yang gagal, route mana yang mencoba memanggil, dan siapa yang bisa memperbaikinya.

Fallback biasanya salah untuk kegagalan auth. Jika sebuah tim belum menyetujui satu provider, berpindah diam-diam ke provider lain dapat melewati procurement, batas data, atau kebijakan model. Respons yang terkendali adalah kegagalan yang jelas, peringatan ke pemilik, dan jalur perbaikan.

Kegagalan kuota dan rate-limit

Kegagalan kuota dan rate-limit adalah kelas yang paling sering dirugikan oleh logika retry yang samar. Sebuah 429 bisa berarti burst pacing, limit request-per-minute, limit token-per-minute, limit request harian, habisnya anggaran bulanan, habisnya kredit prabayar, atau limit berbasis spend. Kasus-kasus tersebut tidak memiliki satu jalur pemulihan yang sama.

Gunakan taksonomi error LLM gateway ini untuk keputusan kuota:

Kuncinya adalah membedakan pacing sementara dari anggaran yang habis. Backoff membantu ketika provider meminta Anda memperlambat. Backoff tidak membantu ketika akun tidak memiliki kredit atau job tidak bisa muat ke budget token yang tersedia.

Pasangkan bagian ini dengan strategi retry AI API Flatkey ketika Anda membutuhkan checklist retry yang lebih mendalam. Buat percobaan retry tetap terlihat di log agar finance dan operations dapat melihat token spend duplikat.

Kegagalan provider dan transport

Kegagalan provider dan transport berbeda dari kegagalan kuota. Artinya request mungkin valid, key mungkin valid, dan budget mungkin tersedia, tetapi route tidak dapat menyelesaikan panggilan.

Sinyal umum meliputi:

Provider fallback bisa berguna di sini, tetapi memerlukan kontrak. Route fallback harus mempertahankan bentuk endpoint, tools, kebutuhan output terstruktur, context window, batas data, persetujuan model, dan batas biaya. Jika streaming sudah menghasilkan token yang terlihat, perilaku yang lebih aman sering kali adalah berhenti dan menampilkan kegagalan yang terkendali alih-alih menyambung output dari route lain.

Gunakan keandalan API AI streaming untuk pemulihan yang spesifik untuk streaming, dan gunakan evaluasi fallback model sebelum mengubah error provider menjadi perubahan rute otomatis.

Request and validation failures

Kegagalan request dan validasi biasanya bukan insiden provider. Ini berarti pemanggil mengirim sesuatu yang tidak dapat diproses oleh endpoint.

Contohnya meliputi field wajib yang hilang, JSON yang tidak valid, parameter yang tidak didukung, keluarga endpoint yang salah, ID model tidak valid, konteks terlalu panjang, skema tool yang tidak didukung, modality yang tidak kompatibel, atau input file/gambar/video yang tidak memenuhi kontrak endpoint.

Gateway harus mencatat field berikut:

Jangan lakukan retry untuk kegagalan validasi yang tidak berubah. Ubah request menjadi bentuk yang valid atau kembalikan error yang dapat dibaca developer yang menyebutkan field yang perlu diperbaiki. Saat gateway mendukung beberapa keluarga endpoint, error validasi menjadi sangat penting karena sebuah request bisa valid untuk satu provider tetapi tidak valid untuk provider lain.

Safety and policy failures

Kegagalan safety dan policy perlu kelas sendiri karena retry dan fallback bisa secara tidak sengaja melemahkan guardrail. Penolakan safety bukan berarti downtime provider. Blok moderasi bukan berarti kuota habis. Output yang diblokir bukan alasan untuk terus melakukan sampling sampai gateway menemukan rute yang mengeluarkan konten terlarang.

Normalisasikan sinyal-sinyal ini ke dalam kelas safety:

Aturan praktisnya sederhana: taksonomi error LLM gateway tidak boleh memperlakukan safety sebagai outage provider yang bisa dipulihkan. Fallback mungkin dapat diterima hanya ketika rute fallback mempertahankan kebijakan safety yang sama atau lebih ketat dan tujuannya adalah menyelesaikan versi aman dari tugas, bukan untuk melewati blok.

The normalized error record

Taksonomi error LLM gateway yang berguna mengubah kegagalan spesifik provider menjadi satu record yang tahan lama.

Jangan reduksi rekaman ini menjadi satu string seperti "Panggilan LLM gagal." String itu tidak cukup untuk memutuskan apakah harus memutar kunci, menunggu, mengisi ulang, fallback, merevisi prompt, atau berhenti.

Klasifikator TypeScript sederhana

Klasifikator tidak perlu mengetahui setiap detail provider pada hari pertama. Mulailah dengan bucket yang eksplisit dan default yang gagal secara konservatif.

type ErrorClass =
  | "auth"
  | "quota"
  | "provider"
  | "request"
  | "safety"
  | "cancelled"
  | "unknown";

type GatewayErrorInput = {
  httpStatus?: number;
  providerErrorType?: string;
  providerErrorCode?: string;
  finishReason?: string;
  stopReason?: string;
  clientCancelled?: boolean;
  timeout?: boolean;
};

function classifyGatewayError(error: GatewayErrorInput): ErrorClass {
  const type = (error.providerErrorType || "").toLowerCase();
  const code = (error.providerErrorCode || "").toLowerCase();
  const stop = (error.stopReason || "").toLowerCase();
  const finish = (error.finishReason || "").toLowerCase();

  if (error.clientCancelled) return "cancelled";

  if (error.httpStatus === 401 || error.httpStatus === 403) return "auth";
  if (type.includes("auth") || type.includes("permission")) return "auth";
  if (code.includes("invalid_api_key") || code.includes("ip_not_authorized")) {
    return "auth";
  }

  if (error.httpStatus === 429) return "quota";
  if (type.includes("rate_limit") || code.includes("quota")) return "quota";
  if (code.includes("resource_exhausted")) return "quota";

  if (stop === "refusal" || finish === "safety") return "safety";
  if (code.includes("moderation") || code.includes("blocked")) return "safety";

  if (error.httpStatus === 400 || error.httpStatus === 422) return "request";
  if (type.includes("invalid_request") || type.includes("bad_request")) {
    return "request";
  }

  if (error.timeout) return "provider";
  if ([500, 502, 503, 504, 529].includes(error.httpStatus || 0)) {
    return "provider";
  }
  if (type.includes("overloaded") || type.includes("api_error")) {
    return "provider";
  }

  return "unknown";
}

Gunakan ini hanya sebagai titik awal. Klasifikator produksi harus menyimpan pemetaan khusus provider di konfigurasi, fixture pengujian, dan peninjauan insiden, bukan hanya tersembunyi di kode aplikasi.

Runbook: retry, queue, fallback, atau fail closed

Setelah kelas diketahui, gateway dapat memilih tindakan.

Tabel ini adalah pusat operasional dari taksonomi error LLM gateway. Tabel ini memberi tahu gateway kapan pekerjaan tambahan masih aman dan kapan pekerjaan tambahan berubah menjadi risiko.

How to apply this in Flatkey

Gunakan taksonomi ini sebagai checklist rollout, bukan proyek dashboard sekali jadi.

1. Pilih satu alur kerja, seperti chat dukungan, ekstraksi batch, job evaluasi, atau traffic code assistant.
2. Tentukan keluarga endpoint yang diizinkan, model, rute fallback, dan batas biaya untuk alur kerja tersebut.
3. Normalisasikan error provider ke field-field di atas.
4. Buat kegagalan auth dan permission terlihat oleh owner serta tidak dapat di-retry.
5. Pisahkan rate limit sementara dari kuota, pengeluaran, dan habisnya limit harian.
6. Wajibkan kontrak fallback sebelum mengganti provider atau model.
7. Perlakukan penolakan safety dan moderasi sebagai hasil policy, bukan outage provider.
8. Catat state output parsial sebelum retry atau fallback apa pun.
9. Tinjau penggunaan dan bukti rute di Flatkey sebelum memperluas ke lebih banyak alur kerja.
10. Tautkan runbook ke harga Flatkey sehingga operator dapat memverifikasi katalog dan permukaan biaya saat ini.

Snapshot API pricing publik Flatkey pada 3 Juli 2026 mengembalikan 45 baris model, enam vendor ID, dan keluarga endpoint yang didukung termasuk openai, anthropic, gemini, dan image-generation. Perlakukan itu hanya sebagai fakta sumber yang bertanggal. Ketersediaan model, harga, dan perilaku rute harus diperiksa ulang sebelum rollout produksi.

FAQ

What is an LLM gateway error taxonomy?

Taksonomi error LLM gateway adalah kumpulan kelas kegagalan yang dinormalisasi untuk traffic model-provider. Ini memisahkan kegagalan auth, quota, provider, request, safety, dan cancellation sehingga gateway dapat memilih perilaku retry, antre, fallback, atau fail-closed.

Why not retry every LLM API error?

Retry semua error dapat memperburuk insiden. Ini dapat memperbesar rate limit, menghabiskan lebih banyak token setelah kuota habis, menyembunyikan kegagalan kredensial, menggandakan output parsial, atau melewati blok safety. Taksonomi menentukan kapan retry benar-benar diizinkan.

Should safety refusals trigger fallback?

Tidak secara default. Penolakan safety, blok moderasi, blok prompt, dan finishReason: SAFETY harus diperlakukan sebagai hasil policy. Fallback tidak boleh digunakan untuk mencari rute safety yang lebih lemah.

How should an LLM gateway classify quota failures?

Pisahkan pacing rate sementara dari pengeluaran yang habis, kredit prabayar, limit harian, limit token, dan limit project. Pacing sementara dapat menggunakan backoff terbatas atau antrean. Anggaran yang habis biasanya fail closed sampai pemilik menyetujui kapasitas tambahan.

How does Flatkey help with an LLM gateway error taxonomy?

Flatkey memberi tim satu permukaan gateway untuk akses model, routing, billing, analitik penggunaan, dan kontrol operasional. Gunakan ini untuk menjaga kelas error yang dinormalisasi tetap terikat pada owner key, keluarga endpoint, model yang diminta, model yang dilayani, dan bukti penggunaan.

Mulailah dengan satu alur kerja, definisikan taksonomi error LLM gateway Anda, lalu dapatkan kunci dan uji kasus auth, quota, provider, request, safety, dan cancellation sebelum traffic produksi bergantung pada recovery otomatis.