/
Susunan respons kesalahan API LinkHarbor, arti kode kesalahan terpenting, dan bagaimana kode Anda sebaiknya menanggapinya.
Setiap respons kesalahan dari API punya format yang sama. Kode Anda sebaiknya mengandalkan kode kesalahan di kolom error, bukan teks di message – kodenya tetap stabil, sedangkan teksnya bisa berubah dan diterjemahkan ke bahasa akun.
Susunan respons kesalahan
{
"error": "validation_failed",
"message": "Some of the information provided is invalid. Please check and try again.",
"details": [
{ "field": "title", "reason": "minLength", "message": "…" }
],
"request_id": "6b1f0c2e-…"
}- error
- Kode yang bisa dibaca mesin, misalnya not_found. Untuk sebagian besar kesalahan, kode ini juga ada di header X-Error-Code – tetapi andalkan kolom di body.
- message
- Deskripsi yang bisa dibaca manusia dalam bahasa akun: dengan kunci API, bahasa pemilik workspace, dengan aplikasi terhubung, bahasa orang yang menghubungkannya. Tanpa token yang valid – misalnya 401 dari pemeriksaan token – bahasanya mengikuti Accept-Language, jika tidak, bahasa Inggris. Header Content-Language menyebutkan bahasanya.
- details
- Hanya ada jika ada hal lain yang perlu disampaikan. Untuk 422 dari validasi isian, sebuah daftar dengan field, reason, dan message untuk setiap masalah; untuk 422 dari logika bisnis dan semua kesalahan lainnya, sebuah objek, misalnya dengan reason, retry_after_sec, atau daftar issues. Saat ukuran terlampaui, isinya field, reason, dan limit, dan untuk 413 request_too_large max_bytes dan max_kb. Jadi periksa apakah details berupa daftar.
- request_id
- ID permintaan. ID ini juga ada di header X-Request-Id. Sertakan saat Anda menghubungi dukungan.
Pengecualian: respons 429 rate_limited punya kolom retry_after_sec alih-alih details; pada 429 dan 403 insufficient_scope, request_id tidak ada di body. 401 dari pemeriksaan token dan 422 dari pemeriksaan skema tidak punya header X-Error-Code, dan pada pemeriksaan skema hanya message tingkat atas yang diterjemahkan; teks di dalam details tetap dalam bahasa Inggris. Header X-Request-Id selalu disetel.
Kode-kode terpenting
| HTTP | error | Arti | Yang harus dilakukan |
|---|---|---|---|
| 400 | invalid_json | Body bukan JSON yang valid | Periksa JSON-nya |
| 400 | bad_request | Content-Type salah atau permintaan cacat | Setel Content-Type: application/json |
| 401 | missing_bearer_token | Tidak ada token di header Authorization | Setel header Authorization: Bearer … |
| 401 | invalid_token | Token kedaluwarsa atau tidak valid, atau kunci dihapus | Ambil token baru; jika tidak membantu, periksa kuncinya |
| 401 | invalid_api_key | ID kunci atau rahasia salah saat penukaran token | Periksa data aksesnya |
| 402 | plan_limit_reached | Batas paket tercapai, misalnya untuk tautan pendek | Upgrade atau hapus entri |
| 403 | insufficient_scope | Scope tidak ada atau endpoint tidak diaktifkan untuk kunci API | Buat kunci dengan scope yang tepat |
| 403 | forbidden | Tidak ada izin untuk tindakan ini | Lakukan di dasbor |
| 403 | feature_not_available | Fitur tidak termasuk dalam paket | Periksa paketnya |
| 403 | block_type_requires_plan | Jenis blok hanya tersedia di paket yang lebih tinggi | Pilih jenis blok lain atau upgrade |
| 403 | template_locked | Templat premium tidak tersedia di paket saat ini | Pilih templat dari GET /v1/templates/available |
| 403 | workspace_suspended, workspace_read_only, workspace_grace_expired | Workspace terkunci atau hanya baca karena pembayaran tertunggak | Selesaikan pembayaran di dasbor |
| 404 | not_found | Resource tidak ada atau bukan milik workspace Anda | Periksa ID-nya |
| 409 | conflict | Konflik umum dengan keadaan saat ini | Muat ulang keadaannya, ubah isiannya |
| 409 | workspace_template_in_use | Templat workspace masih dipakai oleh halaman; jumlahnya ada di details.count | Ganti templat halaman-halaman itu, lalu hapus |
| 409 | handle_taken, slug_taken | Handle atau slug tautan pendek sudah dipakai | Pilih nilai lain |
| 409 | form_in_use, page_not_private, page_not_published, never_published | Konflik dengan keadaan: formulir masih di sebuah halaman, halaman tidak privat atau belum dipublikasikan, belum pernah dipublikasikan | Ubah keadaannya, lalu coba lagi |
| 409 | page_limit_reached, link_limit_reached, block_limit_reached, form_limit_reached, asset_limit_reached, asset_storage_limit_reached, workspace_template_limit_reached | Batas jumlah atau penyimpanan paket tercapai | Hapus entri atau upgrade |
| 409 | draft_not_publishable | Draf punya masalah; daftarnya ada di details.issues | Perbaiki masalahnya, lalu publikasikan lagi |
| 413 | request_too_large | Body lebih besar dari yang diizinkan untuk endpoint ini (64 KB, 1 MB, atau 2 MB); batasnya ada di details.max_kb | Kirim lebih sedikit data per permintaan, lihat Rate limit |
| 413 | payload_too_large | File yang diunggah lebih dari 10 MB | Perkecil filenya |
| 422 | validation_failed | Isian tidak valid atau kolom tidak dikenal; rinciannya di details | Perbaiki kolom-kolomnya sesuai details |
| 422 | handle_reserved, target_url_invalid, target_url_scheme, target_url_host | Handle dicadangkan, atau URL tujuan tidak valid atau tidak diizinkan | Pilih nilai lain |
| 422 | workspace_template_disabled | Templat workspace yang dipilih dinonaktifkan | Aktifkan templat di “Domain & templat” atau pilih yang lain |
| 422 | template_css_external, template_section_invalid | Templat workspace: CSS memuat dari server eksternal, atau bagian {{#if}}/{{#unless}}/{{#each}} ditempatkan salah | Hapus alamat eksternal, atau tutup bagian itu di dalam tag atau teks yang sama |
| 422 | custom_css_external | CSS kustom memuat sesuatu dari server eksternal | Hapus alamat eksternal dari CSS |
| 429 | rate_limited, api_key_locked | Terlalu banyak permintaan, atau kunci dikunci setelah percobaan gagal | Tunggu selama yang disebutkan Retry-After atau details.retry_after_sec |
| 500 | internal_error | Kesalahan yang tidak terduga | Coba lagi nanti, catat request_id-nya |
| 503 | service_unavailable | Layanan sementara tidak tersedia | Coba lagi setelah jeda |
Membaca kesalahan isian
Dengan 422 validation_failed, details mencantumkan setiap masalah secara terpisah: field adalah path kolomnya (dengan garis miring untuk objek bersarang, misalnya theme_config/button_style), reason adalah aturan yang dilanggar, seperti required, minLength, maxLength, enum, atau additionalProperties. Dengan additionalProperties, pesannya menyebutkan kolom mana yang tidak dikenal – sering kali salah ketik pada nama kolom.
Penanganan yang disarankan di kode Anda
- 400, 413, dan 422: jangan ulangi, perbaiki permintaannya
- 401 invalid_token: ambil token baru sekali lalu ulangi
- 403: jangan ulangi; periksa scope, paket, atau siapa yang boleh melakukannya
- 404: periksa ID-nya; setelah penghapusan, ini normal
- 409: muat ulang keadaannya dan putuskan apakah tindakan itu masih diperlukan
- 429: tunggu selama yang disebutkan Retry-After, lalu ulangi – lihat Rate limit
- 500 dan 503: ulangi beberapa kali dengan jeda yang makin lama
Mungkin ini juga berguna
Tidak menemukan jawabannya?
Beri tahu kami apa yang Anda perlukan, dan tim dukungan kami akan membantu Anda secara langsung.