Kode Respons API Rujukan

Berlaku untuk: Pusat Mitra / Referensi Pusat Mitra

Peran yang sesuai: Admin rujukan | Pengguna rujukan

API REST Rujukan pusat mitra mengembalikan objek JSON yang berisi kode status. Kode ini yang menunjukkan apakah permintaan Anda berhasil atau mengapa gagal.

Tanggapan keberhasilan

Kode status 2xx menunjukkan bahwa permintaan klien berhasil diterima, dipahami, dan diterima. Kode status 2xx berikut menunjukkan respons keberhasilan:

• 200: Keberhasilan dikonfirmasi
• 201: Sumber daya dibuat
• 202: Diterima
• 204: Tidak ada konten untuk dikembalikan

Respons kesalahan

Respons apa pun dengan kode status 4xx atau 5xx menyertakan pesan kesalahan dengan detail tentang kondisi kesalahan untuk kode tersebut.

Tabel berikut mencantumkan dan menjelaskan kode status HTTP yang dapat dikembalikan untuk skenario kesalahan.

Kode status	Pesan status	Deskripsi
400	Permintaan Tidak Valid	Tidak dapat memproses permintaan karena bentuknya salah atau tidak benar.
401	Tidak diizinkan	Informasi autentikasi yang diperlukan hilang atau tidak valid untuk sumber daya.
403	Terlarang	Akses ditolak ke sumber daya yang diminta. Pengguna mungkin tidak memiliki cukup izin.
404	Tidak Ditemukan	Sumber daya yang diminta tidak ada.
405	Metode Tidak Diizinkan	Metode HTTP dalam permintaan tidak diizinkan pada sumber daya.
406	Tidak Dapat Diterima	Layanan ini tidak mendukung format yang diminta di header Terima.
409	Konflik	Status saat ini bertentangan dengan harapan dari permintaan. Misalnya, folder induk yang ditentukan mungkin tidak ada.
410	Hilang	Sumber daya yang diminta tidak lagi tersedia di server.
411	Panjang Diperlukan	Diperlukan header Content-Length pada permintaan.
412	Prasyarat gagal	Prasyarat yang disediakan dalam permintaan (seperti header if-match) tidak cocok dengan status sumber daya saat ini.
413	Entitas Permintaan Terlalu Besar	Ukuran permintaan melebihi batas maksimum.
415	Jenis Media Tidak Didukung	Jenis konten permintaan adalah format yang tidak didukung layanan.
416	Rentang yang Diminta Tidak Terpenuhi	Rentang byte yang ditentukan tidak valid atau tidak tersedia.
422	Entitas yang Tidak Dapat Diolah	Tidak dapat memproses permintaan karena secara semantik salah.
423	Terkunci	Sumber daya yang sedang diakses dikunci.
429	Terlalu Banyak Permintaan	Aplikasi klien dibatasi dan tidak boleh mencoba mengulangi permintaan untuk beberapa waktu.
500	Kesalahan Server Internal	Terjadi kesalahan server internal saat memproses permintaan.
501	Tidak Diimplementasikan	Fitur yang diminta tidak diimplementasikan.
503	Layanan Tidak Tersedia	Layanan ini sementara tidak tersedia untuk pemeliharaan atau kelebihan beban. Anda dapat mengulangi permintaan setelah penundaan, yang panjangnya dapat ditentukan dalam header Coba Lagi-Setelah.
504	Waktu Tunggu Gateway Habis	Server, saat bertindak sebagai proksi, tidak menerima respons tepat waktu dari server upstream yang diperlukan untuk mengakses dalam mencoba menyelesaikan permintaan. Dapat terjadi bersama dengan 503.
507	Penyimpanan Tidak Mencukup	Mencapai kuota penyimpanan maksimum.
509	Batas Bandwidth Terlampaui	Aplikasi klien mengalami pembatasan karena melebihi batas bandwidth maksimum. Aplikasi Anda dapat mencoba kembali permintaan lagi setelah beberapa waktu.

Jenis sumber daya kesalahan

Respons kesalahan adalah satu objek JSON yang berisi satu properti bernama kesalahan. Objek ini mencakup semua detail kesalahan. Anda dapat menggunakan informasi yang dikembalikan di sini alih-alih atau selain kode status HTTP.

Contoh tabel dan kode berikut menjelaskan skema respons kesalahan.

Nama	Tipe	Deskripsi
kode	string	Selalu dikembalikan. Menunjukkan jenis kesalahan yang terjadi. Non-null.
pesan	string	Selalu dikembalikan. Menjelaskan kesalahan secara rinci, dan menyediakan informasi debugging lebih lanjut. Non-null nonempty. Panjang maksimum adalah 1.024 karakter.
innerError	objek	Opsional. Objek kesalahan lain dengan informasi yang lebih spesifik tentang kesalahan yang terjadi.
innerError.code	string numerik	Selalu dikembalikan, jika innerError tidak bernilai null. Menyediakan informasi kode kesalahan yang lebih spesifik di bawah nilai kode kesalahan teratas.
pesanKesalahanInternal	string	Selalu dikembalikan, jika innerError tidak null. Menyediakan pesan kesalahan yang lebih spesifik di bawah string pesan kesalahan teratas.
innerError.details	array objek	Opsional. Berisi detail lebih lanjut tentang kesalahan tersebut. Terutama berguna dalam kesalahan validasi input.
sasaran	string	Opsional. Tempat sasaran dari mana kesalahan berasal.

Contoh respons kesalahan

{
  "error": {
    "code": "unauthenticated",
    "message": "The caller is not authenticated.",
    "innerError": {
      "code": "99902",
      "message": "Request not authenticated",
      "details": null
    }
  }
}

Sampel lain dengan objek innerError.details diisi:

{
  "error": {
    "code": "invalidRequest",
    "message": "The request is malformed or incorrect.",
    "innerError": {
      "code": "99901",
      "message": "InvalidInput",
      "details": [
        {
          "InvalidReferralForCoSellConversion": [
            "If PartnerLed referral has no solution it cannot be converted to co-sell referral"
          ]
        }
      ]
    }
  }
}

Properti kode

Properti code berisi salah satu nilai yang mungkin berikut ini. Aplikasi Anda harus disiapkan untuk menangani salah satu kesalahan ini.

Kode	Kode status HTTP	Deskripsi
invalidRequest	400	Permintaan salah bentuk atau salah.
tidak terautentikasi	401	Pemanggil tidak diautentikasi.
accessDenied	403	Pemanggil tidak memiliki izin untuk melakukan tindakan.
itemNotFound	404	Sumber daya tidak dapat ditemukan.
sumberDiperbarui	409	Sumber daya yang sedang diperbarui telah berubah sejak terakhir kali dibaca oleh pemanggil, biasanya karena ketidakcocokan eTag.
preconditionFailed	412	Prasyarat yang disediakan dalam permintaan (seperti header if-match) tidak cocok dengan status sumber daya saat ini.
generalException	500	Terjadi kesalahan yang tidak ditentukan.
serviceNotAvailable	503	Layanan ini tidak tersedia. Coba permintaan lagi setelah penundaan. Mungkin ada header Coba Lagi-Setelah.

Properti pesan

Properti message di akar berisi pesan kesalahan yang ditujukan untuk dibaca pengembang. Pesan kesalahan tidak dilokalkan dan tidak boleh ditampilkan langsung kepada pengguna. Kode Anda tidak boleh memeriksa message nilai hanya karena dapat berubah kapan saja, dan sering berisi informasi dinamis khusus untuk permintaan yang gagal. Anda harus menulis kode untuk menangani kode kesalahan yang dikembalikan di properti code dan kemudian untuk detail lebih lanjut menggabungkannya dengan teks pesan.

Objek InnerError

Objek innererror mungkin secara rekursif berisi lebih innererror banyak objek dengan kode kesalahan yang lebih spesifik. Aplikasi klien, saat menangani kesalahan, harus mengulangi semua kode kesalahan yang tersedia dan menggunakan yang paling rinci yang mereka pahami.

Ada beberapa kesalahan lain yang mungkin ditemui aplikasi Anda dalam objek berlapis innererror . Aplikasi tidak diperlukan untuk menangani kesalahan ini, tetapi dapat melakukannya jika mereka memilih. Layanan mungkin menambahkan kode kesalahan baru atau berhenti mengembalikan kode lama kapan saja, jadi penting bagi semua aplikasi untuk dapat menangani [kode kesalahan dasar].

Kode kesalahan

Berikut ini adalah kode kesalahan yang dikembalikan oleh API:

HTTP Status	Kode Galat HTTP	Kode kesalahan	Deskripsi
BadRequest	400	99901	Input tidak valid
Tidak diizinkan	401	99902	Akses yang tidak sah
Permintaan Tidak Valid	400	99903	Input hilang
Tidak Ditemukan	404	99904	Sumber daya tidak ditemukan
InternalServerError	500	99905	Kesalahan tidak ditentukan
TerlaluBanyakPermintaan	429	99906	Terlalu banyak permintaan
InternalServerError	500	99907	Kesalahan internal sementara
BadRequest	400	99908	Properti tidak dapat diperbarui
Permintaan Tidak Valid	400	99909	Properti tidak dapat bernilai null
PrasyaratGagal	412	99910	Nilai Etag tidak cocok
Permintaan Tidak Valid	400	99911	Status rujukan tidak valid untuk mengundang
Kesalahan Permintaan	400	99912	Solusi dengan jenis 'nama' diperlukan
Terlarang	403	99913	Organisasi tidak diizinkan untuk membuat sumber daya
Terlarang	403	99914	Organisasi tidak diizinkan untuk berpartisipasi dalam keterlibatan penjualan bersama
InternalServerError	500	99915	Kegagalan pelaksanaan permintaan internal
Konflik	409	99917	Sumber daya sudah dimodifikasi melalui permintaan lain
PrasyaratGagal	412	99918	Prasyarat yang disediakan dalam permintaan (seperti header if-match) tidak cocok dengan status sumber daya saat ini.
BadRequest	400	99919	Kualifikasi rujukan tidak valid untuk pembaruan
InternalServerError	500	99999	Pengecualian umum saat memproses permintaan