Format Respon Kesalahan

API GraphQL Blue mengembalikan kesalahan dalam format standar yang mengikuti spesifikasi GraphQL. Ketika kesalahan terjadi, respon mencakup array errors dengan informasi rinci tentang apa yang salah.

Contoh Respon Kesalahan

{
  "errors": [
    {
      "message": "Todo was not found.",
      "extensions": {
        "code": "TODO_NOT_FOUND"
      }
    }
  ]
}

Struktur Kesalahan

Setiap objek kesalahan berisi:

• message: Deskripsi kesalahan yang dapat dibaca manusia
• extensions.code: Kode kesalahan yang dapat dibaca mesin untuk penanganan programatik

Keamanan Kesalahan Produksi

Blue menerapkan sistem keamanan untuk paparan kesalahan:

• Kesalahan Aman: Menampilkan kode kesalahan dan pesan yang sebenarnya kepada klien
• Kesalahan Tidak Aman: Mengembalikan INTERNAL_SERVER_ERROR generik untuk menyembunyikan detail sensitif
• Sumber Daya Tidak Ditemukan: Semua kesalahan *_NOT_FOUND dianggap aman dan selalu dipaparkan

Kategori Kesalahan

Blue mendefinisikan 108 kode kesalahan kustom yang diorganisir ke dalam kategori berikut:

Kesalahan Autentikasi & Otorisasi

Kesalahan Sumber Daya Tidak Ditemukan (52 total)

Sumber Daya Inti

Bidang Kustom & Formulir

Komponen Proyek

Komentar & Aktivitas

Sumber Daya Lainnya

Kesalahan Validasi

Kesalahan Logika Bisnis

Batas & Kuota

Konflik Sumber Daya

Kesalahan Izin & Akses

Kesalahan Integritas Data

Kesalahan Stripe/Pembayaran

Kesalahan Autentikasi & Sesi

Pembatasan Laju

Pembatasan laju ditangani oleh paket graphql-rate-limit dengan konfigurasi yang berbeda:

Ketika dibatasi, Anda akan menerima kesalahan GraphQL standar dengan pesan yang menunjukkan batas terlampaui.

Kesalahan Sistem & Internal

Praktik Terbaik Penanganan Kesalahan

Penanganan Sisi Klien

try {
  const result = await client.mutate({
    mutation: CREATE_TODO,
    variables: { input }
  });
} catch (error) {
  if (error.graphQLErrors?.length > 0) {
    const errorCode = error.graphQLErrors[0].extensions?.code;
    
    switch (errorCode) {
      case 'UNAUTHENTICATED':
        // Redirect to login
        break;
      case 'TODO_NOT_FOUND':
        // Show "Record not found" message
        break;
      case 'VALIDATION_ERROR':
        // Display validation errors
        break;
      default:
        // Show generic error message
    }
  }
}

Skenario Kesalahan Umum

1. Autentikasi Diperlukan: UNAUTHENTICATED - Pengguna perlu masuk
2. Izin Ditolak: FORBIDDEN - Pengguna tidak memiliki peran/izin yang diperlukan
3. Sumber Daya Tidak Ditemukan: *_NOT_FOUND - Sumber daya tidak ada atau pengguna tidak dapat mengaksesnya
4. Validasi Gagal: VALIDATION_ERROR, BAD_USER_INPUT - Periksa parameter input
5. Pembatasan Laju: Periksa header batas laju dan terapkan penundaan
6. Pembayaran Diperlukan: PAYMENT_REQUIRED - Fitur memerlukan langganan

Dokumentasi Terkait

• Autentikasi - Cara mengautentikasi permintaan API
• Melakukan Permintaan - Format dan header permintaan
• Batas Laju - Informasi rinci tentang pembatasan laju