upstream_error — Layanan pihak ketiga menolak

upstream_error adalah kode error HTTP 502 pada Se-Hari API. Kami meneruskan permintaan Anda ke layanan lain — Zoom untuk meeting, penyedia AI untuk transkripsi — dan layanan itu yang gagal. Masalahnya bukan pada request Anda.

#Bentuk responsnya

Semua error Se-Hari memakai amplop yang sama. Yang perlu dicabang di kode Anda adalah code, bukan message — teks pesan bisa kami perbaiki sewaktu-waktu, sedangkan code adalah kontrak publik yang hanya berubah lewat versi API baru.

{
  "error": {
    "code": "upstream_error",
    "message": "Contoh pesan untuk upstream_error.",
    "docs_url": "https://se-hari.com/docs/error/upstream-error",
    "request_id": "req_a1b2c3d4e5f6",
    "details": {
      "upstream": "zoom"
    }
  }
}

#Kapan ini muncul

Kode ini memisahkan kegagalan kami dari kegagalan pihak ketiga, dan pemisahan itu berguna: 502 berarti request Anda sudah sampai, sudah divalidasi, dan sudah diteruskan — yang gagal adalah langkah setelahnya. Tidak ada yang perlu diperbaiki pada bentuk request Anda.

#Kenapa ini terjadi

• Zoom sedang mengalami gangguan
• Kuota atau lisensi Zoom di sisi kami sedang habis
• Penyedia AI menolak berkas dengan format yang tidak biasa

#Cara memperbaikinya

Coba lagi dengan jeda yang membesar dan Idempotency-Key yang sama. Kalau terus berulang lebih dari beberapa menit, laporkan dengan request_id — kami perlu melihat balasan mentah dari pihak ketiga untuk tahu apa yang sebenarnya ditolak.

#Yang memicu error

# Retry ketat tanpa jeda hanya memperbesar antrean yang sudah macet
for i in $(seq 1 50); do curl -X POST "https://se-hari.com/api/v1/meetings" ...; done

#Yang seharusnya

# Jeda yang membesar
for percobaan in 1 2 3 4; do
  status=$(curl -s -o /dev/null -w '%{http_code}' -X POST "https://se-hari.com/api/v1/meetings" \
    -H "Idempotency-Key: $KEY" -H "Authorization: Bearer $SEHARI_API_KEY" \
    -H "Content-Type: application/json" -d "$BODY")
  [ "$status" = "502" ] || break
  sleep $((2 ** percobaan))
done

#Aman diulang?

Ya, dengan jeda yang membesar dan Idempotency-Key yang sama. Batasi jumlah percobaannya; gangguan pihak ketiga bisa berlangsung lama, dan antrean retry tak terbatas akan membebani sistem Anda sendiri sebelum sempat berhasil.

#Jangan tertukar dengan

Kalau yang gagal komponen kami sendiri, kodenya internal_error (500). Kalau kami sedang tidak siap melayani sama sekali — misalnya saat deploy — kodenya service_unavailable (503). Ketiganya sama-sama layak di-retry, tapi hanya kode ini yang penyebabnya berada sepenuhnya di luar kendali kami berdua.

#Mencegahnya terulang

Perlakukan 502 sebagai kondisi sementara dengan jeda yang membesar, bukan sebagai kegagalan permanen. Namun batasi jumlah percobaannya: gangguan pihak ketiga bisa berlangsung berjam-jam, dan antrean retry yang tidak dibatasi akan menumpuk sampai membebani sistem Anda sendiri. Setelah beberapa percobaan, lebih baik menahan pekerjaan dan memberi tahu manusia daripada terus mencoba diam-diam.

#Menangani ini di kode

Cabangkan pada error.code, dan bedakan kegagalan yang layak diulang dari yang tidak. Mengulang kegagalan yang tidak akan pernah berhasil hanya menghabiskan kuota rate limit — dan menyembunyikan kegagalan yang sebenarnya butuh perhatian Anda.

const res = await fetch('https://se-hari.com/api/v1/me', {
	headers: { Authorization: `Bearer ${process.env.SEHARI_API_KEY}` }
});

if (!res.ok) {
	const { error } = await res.json();

	if (error.code === 'upstream_error') {
		// Coba lagi dengan jeda yang membesar dan `Idempotency-Key` yang sama. Kalau terus…
		console.error(error.message, error.details);
	}

	// request_id adalah satu-satunya cara kami menemukan request ini di log.
	console.error(`request_id: ${error.request_id}`);
}

#Selanjutnya

• Semua kode error — daftar lengkap
• Autentikasi — scope dan siklus hidup API key
• Referensi API — error apa saja yang mungkin muncul di tiap endpoint