Ralat

Satu bentuk untuk setiap kegagalan, dengan kod yang tidak berubah.

Setiap jawapan membawa medan ok. Semaknya dahulu, sebelum membaca data.

Jawapan gagal

{
  "ok": false,
  "code": "SKOP_TIDAK_CUKUP",
  "message": "Kunci ini tiada skop \"order.read\". Tambah skop itu pada kunci di panel admin."
}

Bercabanglah pada code, jangan pada message. Ayat ditulis untuk manusia dan akan berubah apabila seseorang memperbaiki perkataannya; kod tidak. Integrasi yang membandingkan teks akan rosak pada hari kami membetulkan satu huruf — dan rosaknya senyap, kerana cabang else biasanya bermakna "anggap berjaya".

Senarai kod

Kod	HTTP	Sebab	Cara membetulkan
TIADA_KEBENARAN	401	Kunci tiada, salah bentuk, tidak dikenali, atau sudah dibatalkan.	Semak pengepala Authorization. Kalau kunci hilang, buat yang baharu.
SKOP_TIDAK_CUKUP	403	Kunci sah, tetapi tiada skop untuk endpoint ini.	Buat kunci baharu dengan skop yang disenaraikan pada endpoint itu. Skop tidak boleh ditambah pada kunci sedia ada.
PARAMETER_SALAH	400	Parameter wajib tiada, atau nilainya di luar senarai yang dibenarkan.	Mesej menyebut parameter mana. Semak rujukan endpoint.
TIDAK_DIJUMPAI	404	Rekod tiada — ATAU ia milik kedai lain.	Sengaja tidak dibezakan: memberitahu bahawa rekod itu wujud tetapi milik orang lain sudah merupakan kebocoran.
TERLALU_BANYAK	429	Had kadar dicapai.	Tunggu sehingga masa dalam pengepala Retry-After.
BELUM_DIKONFIGURASI	503	Pelayan belum mempunyai kunci aplikasi, jadi kunci API tidak boleh disahkan.	Masalah pada pelayan kami, bukan pada kunci anda. Hubungi pentadbir kedai.
RALAT_PELAYAN	500	Ralat tidak dijangka.	Cuba lagi. Kalau berulang, laporkan beserta masa dan endpointnya.

Mengendalikannya

JavaScript

async function panggil(laluan, kunci) {
  const r = await fetch(laluan, { headers: { Authorization: `Bearer ${kunci}` } });
  const body = await r.json();

  if (body.ok) return body;

  switch (body.code) {
    case "TERLALU_BANYAK": {
      const tunggu = Number(r.headers.get("retry-after") || 60);
      await new Promise((s) => setTimeout(s, tunggu * 1000));
      return panggil(laluan, kunci);
    }
    case "TIADA_KEBENARAN":
    case "SKOP_TIDAK_CUKUP":
      // Mencuba lagi tidak akan menolong. Beritahu manusia.
      throw new Error(`Kunci bermasalah: ${body.message}`);
    default:
      throw new Error(`${body.code}: ${body.message}`);
  }
}

Perhatikan bahagian yang TIDAK dicuba semula. Kunci yang salah tidak menjadi betul dengan menunggu, dan mencuba semula selama-lamanya hanya menyembunyikan masalahnya daripada orang yang boleh membetulkannya.

Seterusnya: Had kadar →