Claude API 500 api_error dan 502 Bad Gateway — kebijakan percobaan ulang yang benar-benar memulihkan

500 dan 502 berarti terjadi kesalahan, bukan batas penggunaan. Karena itu, keduanya adalah kelas kesalahan dalam kelompok ini yang layak dicoba ulang hampir segera — berbeda dari 429, yang merupakan batas laju Anda sendiri, dan 529, yang berarti penyedia sedang penuh. Mengulangi yang salah dari ketiganya mengubah insiden kecil menjadi insiden Anda sendiri.

Error

dua bentuk, solusi yang sama

// Straight from the model provider (HTTP 500)
{
  "type": "error",
  "error": { "type": "api_error", "message": "Internal server error" }
}

// From a gateway or proxy in between (HTTP 502)
{
  "error": {
    "message": "Failed to reach upstream provider",
    "type": "upstream_error",
    "code": "upstream_error",
    "param": null
  }
}

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Kesalahan sementara di sisi penyedia	Coba ulang dengan exponential backoff dan jitter, dibatasi hingga ~5 percobaan.
Koneksi diterima, lalu tidak pernah dijawab	Hang, bukan kesalahan. Batasi waktu hingga byte pertama secara terpisah dari durasi total.
Perantara yang mengembalikan 502 miliknya sendiri	Tidak berkaitan dengan model. Periksa apakah isi respons berbentuk milik penyedia atau proxy.
Mencoba ulang secara membabi buta selama insiden nyata	Batasi jumlah percobaan dan gunakan backoff — jika tidak, percobaan ulang Anda menjadi bagian dari gangguan.

Bedakan 500 dari 529 dan 429 sebelum memilih solusi

429 adalah batas laju yang Anda lampaui — perlambat. 529 berarti penyedia berada pada kapasitas maksimum — lakukan backoff yang jauh lebih kuat dan lebih lama. 500/502 adalah kesalahan, biasanya singkat dan sering kali spesifik pada satu permintaan. Hanya yang ketiga yang layak segera dicoba ulang, dan memperlakukan ketiganya sama adalah alasan loop percobaan ulang memperburuk insiden.

Coba ulang 5xx, jangan pernah 4xx

Exponential backoff dengan jitter, maksimum lima percobaan. Helper yang sama berfungsi untuk setiap penyedia — 400 atau 422 akan gagal dengan cara yang sama pada percobaan berikutnya, sehingga mengulanginya hanya menghabiskan latensi untuk mencapai kesalahan yang sama.

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Batasi waktu hingga byte pertama secara terpisah dari durasi total

Satu timeout untuk seluruh permintaan tidak dapat membedakan generasi yang lama dari koneksi yang mati. Tetapkan batas waktu singkat untuk byte pertama dan batas waktu longgar untuk sisanya; hang akan gagal dengan cepat, sedangkan jawaban yang benar-benar lambat dibiarkan.

Catat status dan latensi setiap percobaan

Tanpa catatan per percobaan, insiden penyedia dan timeout Anda sendiri tampak sama setelah kejadian. Kode status, latensi, dan nomor percobaan sudah cukup untuk membedakannya keesokan paginya.

Jika Anda melakukan panggilan melalui Kunavo

Per September 2026, setiap model Claude di Kunavo disajikan melalui satu kanal upstream, sehingga 5xx dari kanal tersebut tidak dicoba ulang di dalam permintaan: respons tersebut sampai kepada Anda sebagai 502 dengan pesan “Upstream provider error” (bertipe api_error pada /v1/messages), dan permintaan dicatat dengan biaya nol. Percobaan ulang di dalam permintaan Kunavo hanya berjalan untuk model dengan kanal kedua yang dikonfigurasi: timeout, 5xx, 429, atau penolakan terhadap kunci upstream milik Kunavo akan dicoba ulang pada kanal tersebut sebelum mencapai Anda, pada /v1/messages, /v1/responses, dan model Claude pada /v1/chat/completions. Stream ditahan hingga konten pertamanya tiba, sehingga kesalahan di dalam stream yang belum dimulai juga dicoba ulang; setelah konten mengalir, kegagalan di tengah stream harus Anda tangani sendiri. Apa pun kondisinya, pertahankan kebijakan percobaan ulang di halaman ini pada sisi Anda. Perutean di balik perilaku tersebut dijelaskan dalam panduan gateway AI kami.

Pertanyaan umum

Apakah saya dikenai biaya untuk permintaan yang mengembalikan 500?

Di Kunavo, tidak — permintaan yang gagal dicatat dengan biaya nol. Penagihan langsung oleh penyedia berbeda-beda, tetapi 5xx umumnya tidak dikenai biaya.

Dapatkah percobaan ulang 500 menghasilkan dua penyelesaian?

Ya. Permintaan dapat gagal setelah model selesai menghasilkan. Jika pekerjaan tersebut memiliki efek samping, jadikan pekerjaan itu idempoten pada lapisan Anda sebelum menambahkan percobaan ulang.

Apa perbedaan satu baris antara 500, 502, dan 529?

500 berarti penyedia mengalami kesalahan, 502 berarti sesuatu di depannya gagal menjangkau penyedia, dan 529 berarti penyedia berada pada kapasitas maksimum — coba ulang dua yang pertama segera, dan yang ketiga jauh lebih lambat.

Panduan terkait

Detail semantik error lainnya tersedia di referensi error; mendapatkan kunci hanya perlu satu menit melalui pendaftaran dan panduan autentikasi.