Referensi komprehensif semua kode kesalahan di API GraphQL Blue, diorganisir berdasarkan kategori
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
| Kode Kesalahan |
Pesan |
Deskripsi |
UNAUTHENTICATED |
"Autentikasi diperlukan." |
Permintaan memerlukan autentikasi tetapi tidak ada yang diberikan |
FORBIDDEN |
"Anda tidak diizinkan." |
Terautentikasi tetapi tidak memiliki izin yang diperlukan |
Kesalahan Sumber Daya Tidak Ditemukan (52 total)
Sumber Daya Inti
| Kode Kesalahan |
Pesan |
Deskripsi |
TODO_NOT_FOUND |
"Todo tidak ditemukan." |
Rekaman/todo tidak ada atau pengguna tidak memiliki akses |
TODO_LIST_NOT_FOUND |
"Daftar todo tidak ditemukan." |
Daftar tidak ada atau pengguna tidak memiliki akses |
PROJECT_NOT_FOUND |
"Proyek tidak ditemukan." |
Proyek tidak ada atau pengguna tidak memiliki akses |
COMPANY_NOT_FOUND |
"Perusahaan tidak ditemukan." |
Perusahaan tidak ada atau pengguna tidak memiliki akses |
USER_NOT_FOUND |
"Pengguna tidak ditemukan." |
Pengguna tidak ada dalam sistem |
| Kode Kesalahan |
Pesan |
Deskripsi |
CUSTOM_FIELD_NOT_FOUND |
"Bidang kustom tidak ditemukan." |
Bidang kustom tidak ada |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"Opsi bidang kustom tidak ditemukan." |
Opsi bidang pilih tidak ada |
FORM_NOT_FOUND |
"Formulir tidak ditemukan." |
Template formulir tidak ada |
FORM_FIELD_NOT_FOUND |
"Bidang formulir tidak ditemukan." |
Bidang formulir tidak ada |
Komponen Proyek
| Kode Kesalahan |
Pesan |
Deskripsi |
TAG_NOT_FOUND |
"Tag tidak ditemukan." |
Tag tidak ada dalam proyek |
AUTOMATION_NOT_FOUND |
"Automasi tidak ditemukan." |
Aturan automasi tidak ada |
CHART_NOT_FOUND |
"Grafik tidak ditemukan." |
Grafik dasbor tidak ada |
WEBHOOK_NOT_FOUND |
"Webhook tidak ditemukan." |
Konfigurasi webhook tidak ada |
TEMPLATE_NOT_FOUND |
"Template tidak ditemukan." |
Template proyek tidak ada |
Komentar & Aktivitas
| Kode Kesalahan |
Pesan |
Deskripsi |
COMMENT_NOT_FOUND |
"Komentar tidak ditemukan." |
Komentar tidak ada |
ACTIVITY_NOT_FOUND |
"Aktivitas tidak ditemukan." |
Entri log aktivitas tidak ada |
REACTION_NOT_FOUND |
"Reaksi tidak ditemukan." |
Reaksi komentar tidak ada |
Sumber Daya Lainnya
| Kode Kesalahan |
Pesan |
Deskripsi |
FILE_NOT_FOUND |
"File tidak ditemukan." |
Lampiran file tidak ada |
SUBSCRIPTION_NOT_FOUND |
"Langganan tidak ditemukan." |
Langganan penagihan tidak ada |
INVOICE_NOT_FOUND |
"Faktur tidak ditemukan." |
Rekaman faktur tidak ada |
CHECKLIST_NOT_FOUND |
"Checklist tidak ditemukan." |
Checklist tidak ada |
CHECKLIST_ITEM_NOT_FOUND |
"Item checklist tidak ditemukan." |
Item checklist tidak ada |
PROJECT_ROLE_NOT_FOUND |
"Peran proyek tidak ditemukan." |
Peran proyek kustom tidak ada |
PROJECT_ACCESS_NOT_FOUND |
"Akses proyek tidak ditemukan." |
Akses proyek pengguna tidak ada |
NOTIFICATION_NOT_FOUND |
"Notifikasi tidak ditemukan." |
Notifikasi tidak ada |
DASHBOARD_NOT_FOUND |
"Dasbor tidak ditemukan." |
Dasbor tidak ada |
KEY_NOT_FOUND |
"Kunci tidak ditemukan." |
Kunci pengaturan tidak ada |
Kesalahan Validasi
| Kode Kesalahan |
Pesan |
Deskripsi |
BAD_USER_INPUT |
"Input tidak valid." |
Kegagalan validasi input generik |
VALIDATION_ERROR |
"Parameter tidak valid" |
Parameter permintaan gagal validasi |
BAD_EMAIL |
"Anda perlu memasukkan email yang valid." |
Format email tidak valid |
INVALID_IDS |
"ID tidak valid." |
Satu atau lebih ID dalam permintaan tidak valid |
PHONE_INVALID |
"Telepon tidak valid." |
Format nomor telepon tidak valid |
URL_INVALID |
"URL tidak valid." |
Format URL tidak valid |
INVALID_RECURRING_DUE_DATE |
"Tanggal jatuh tempo tidak valid untuk tugas berulang" |
Validasi tanggal tugas berulang gagal |
INVALID_COLOR |
"Warna tidak valid" |
Nilai warna tidak sesuai dengan format yang diharapkan |
Kesalahan Logika Bisnis
Batas & Kuota
| Kode Kesalahan |
Pesan |
Deskripsi |
COMPANY_LIMIT |
"Anda telah mencapai batas perusahaan untuk akun Anda." |
Batas maksimum perusahaan tercapai |
PROJECT_LIMIT |
"Anda telah mencapai batas proyek untuk perusahaan Anda." |
Batas maksimum proyek tercapai |
USER_LIMIT |
"Anda telah mencapai batas pengguna untuk perusahaan Anda." |
Batas maksimum pengguna tercapai |
PROJECT_TEMPLATE_LIMIT |
"Anda telah mencapai batas template untuk perusahaan Anda." |
Batas maksimum template tercapai |
CUSTOM_FIELD_LIMIT |
"Batas bidang kustom tercapai." |
Batas maksimum bidang kustom tercapai |
TODO_LIST_LIMIT |
"Anda telah mencapai batas daftar untuk proyek Anda." |
Batas maksimum daftar per proyek |
TOO_MANY_TODOS |
"Terlalu banyak todo." |
Batas rekaman terlampaui |
TOO_MANY_OPTIONS |
"Terlalu banyak opsi." |
Batas opsi bidang pilih terlampaui |
MAX_FILE_SIZE |
"Ukuran file maksimum adalah 4.8gb" |
Batas ukuran unggahan file terlampaui |
Konflik Sumber Daya
| Kode Kesalahan |
Pesan |
Deskripsi |
TAG_ALREADY_EXISTS |
"Tag sudah ada." |
Tag dengan nama yang sama ada dalam proyek |
COMPANY_SLUG_ALREADY_EXISTS |
"Perusahaan sudah ada." |
Slug/URL perusahaan sudah digunakan |
USER_ALREADY_EXISTS |
"Pengguna sudah ada." |
Email pengguna sudah terdaftar |
ALREADY_INVITED |
"Pengguna sudah diundang." |
Pengguna sudah memiliki undangan yang tertunda |
USER_ALREADY_IN_PROJECT |
"Pengguna sudah ada di proyek ini." |
Pengguna sudah memiliki akses proyek |
FILE_TYPE_NOT_ALLOWED |
"Tipe file tidak diizinkan." |
Tipe file yang diunggah dibatasi |
Kesalahan Izin & Akses
| Kode Kesalahan |
Pesan |
Deskripsi |
UNABLE_TO_DELETE_ONLY_ADMIN |
"Tidak dapat menghapus satu-satunya Admin di perusahaan." |
Tidak dapat menghapus admin terakhir |
UNABLE_TO_UPDATE_OWNER |
"Tidak dapat memperbarui PEMILIK." |
Tidak dapat mengubah izin pemilik |
TODO_LIST_IS_HIDDEN |
"Daftar todo tersembunyi." |
Daftar tersembunyi dari peran pengguna |
COMPANY_NOT_ACTIVE |
"Perusahaan tidak aktif." |
Langganan perusahaan tidak aktif |
PROJECT_NOT_ACTIVE |
"Proyek tidak aktif." |
Proyek diarsipkan/tidak aktif |
Kesalahan Integritas Data
| Kode Kesalahan |
Pesan |
Deskripsi |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"Tidak dapat menghapus daftar dengan todo." |
Daftar harus kosong untuk dihapus |
UNABLE_TO_DELTE_FILE |
"Tidak dapat menghapus file." |
Penghapusan file gagal (kesalahan ketik dalam kode) |
UNABLE_TO_MOVE_TODO |
"Tidak dapat memindahkan todo." |
Tidak dapat memindahkan rekaman antar daftar |
DEPENDENCY_HAS_DEPENDENCY |
"Ketergantungan memiliki ketergantungan" |
Ketergantungan melingkar terdeteksi |
TODO_DEPENDS_ON_ITSELF |
"Todo bergantung pada dirinya sendiri" |
Ketergantungan referensi diri |
Kesalahan Stripe/Pembayaran
| Kode Kesalahan |
Pesan |
Deskripsi |
STRIPE_CREATING_CUSTOMER |
"Kesalahan saat membuat pelanggan di stripe." |
Pembuatan pelanggan Stripe gagal |
STRIPE_ALREADY_SUBSCRIBED |
"Sudah berlangganan." |
Langganan aktif ada |
STRIPE_MISSING_PAYMENT_METHOD |
"Metode pembayaran hilang." |
Tidak ada metode pembayaran yang terdaftar |
STRIPE_CREATING_SUBSCRIPTION |
"Kesalahan saat membuat langganan di stripe." |
Pembuatan langganan gagal |
STRIPE_UPDATING_SUBSCRIPTION |
"Kesalahan saat memperbarui langganan di stripe." |
Pembaruan langganan gagal |
STRIPE_CHECKOUT_SESSION |
"Kesalahan saat membuat sesi checkout di stripe." |
Pembuatan sesi checkout gagal |
STRIPE_CUSTOMER_PORTAL |
"Kesalahan saat membuat portal pelanggan di stripe." |
Pembuatan sesi portal gagal |
STRIPE_TAX_ID |
"Tidak dapat menyimpan ID pajak" |
Validasi/simpan ID pajak gagal |
PAYMENT_REQUIRED |
"Pembayaran diperlukan." |
Fitur memerlukan langganan aktif |
NO_PAYMENT_REQUIRED |
"Tidak ada pembayaran yang diperlukan." |
Pembayaran tidak diperlukan untuk operasi |
Kesalahan Autentikasi & Sesi
| Kode Kesalahan |
Pesan |
Deskripsi |
INVALID_CREDENTIALS |
"Kredensial tidak valid." |
Nama pengguna/kata sandi salah |
EXPIRED_RESET_TOKEN |
"Token reset telah kedaluwarsa." |
Token reset kata sandi kedaluwarsa |
OAUTH_FAILED |
"Proses OAuth gagal." |
Autentikasi OAuth gagal |
SAML_NOT_ENABLED |
"SSO (SAML) tidak diaktifkan." |
SSO SAML tidak dikonfigurasi |
SSO_AUTO_PROVISION_DISABLED |
"Auto provision dinonaktifkan." |
Tidak dapat membuat pengguna SSO secara otomatis |
Pembatasan Laju
Pembatasan laju ditangani oleh paket graphql-rate-limit dengan konfigurasi yang berbeda:
| Jenis Batas |
Jendela |
Permintaan Maks |
Diterapkan Pada |
| Standard |
60s |
500 |
Most queries/mutations |
| Sensitive |
300s |
10 |
Password reset, auth operations |
| Expensive |
60s |
20 |
Complex queries, bulk operations |
| Search |
60s |
60 |
Search operations |
| File Upload |
60s |
100 |
File upload operations |
Ketika dibatasi, Anda akan menerima kesalahan GraphQL standar dengan pesan yang menunjukkan batas terlampaui.
Kesalahan Sistem & Internal
| Kode Kesalahan |
Pesan |
Deskripsi |
INTERNAL_SERVER_ERROR |
"Kesalahan server internal." |
Kesalahan generik untuk kesalahan tidak aman dalam produksi |
UNKNOWN_ERROR |
"Kesalahan tidak dikenal." |
Kesalahan tak terduga terjadi |
RESOLVER_NOT_FOUND |
"Resolver tidak ditemukan" |
Resolver GraphQL hilang |
FIELD_NOT_IN_SCHEMA |
"Field tidak ada dalam skema" |
Field yang diminta tidak ada |
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
- Autentikasi Diperlukan:
UNAUTHENTICATED - Pengguna perlu masuk
- Izin Ditolak:
FORBIDDEN - Pengguna tidak memiliki peran/izin yang diperlukan
- Sumber Daya Tidak Ditemukan:
*_NOT_FOUND - Sumber daya tidak ada atau pengguna tidak dapat mengaksesnya
- Validasi Gagal:
VALIDATION_ERROR, BAD_USER_INPUT - Periksa parameter input
- Pembatasan Laju: Periksa header batas laju dan terapkan penundaan
- Pembayaran Diperlukan:
PAYMENT_REQUIRED - Fitur memerlukan langganan
Dokumentasi Terkait