Kode kesalahan

Kode status HTTP Listings API, kode kesalahan SYxxxxx untuk Listings dan Social, serta tiga bentuk respons kesalahan yang dikembalikan oleh API v4.

Listings API menggunakan kode status HTTP konvensional untuk melaporkan hasil permintaan. Kode kesalahan memiliki awalan SY dan disertakan di dalam string kesalahan message, dengan format SYxxxxx: <human-readable reason>.

Kode status HTTP

HTTP status code summary

Status	Arti	Kode `SY` yang umum	Exception Python SDK
`200 OK`	Permintaan berhasil. Untuk operasi tulis, periksa juga isi respons (lihat di bawah).	-	-
`400 Bad Request`	Permintaan dengan format yang salah, filter yang tidak dapat diurai, nilai enum yang tidak valid, atau ID dengan format yang salah.	`SY90006`, `SY90001`	`ValidationError`
`401 Unauthorized`	Kunci API tidak disertakan, memiliki format yang salah, atau telah dicabut. Belum memiliki kunci? Dapatkan akses harian sandbox gratis saat tersedia.	`SY90005`	`AuthenticationError`
`402 Payment Required`	Akun memiliki faktur yang belum dibayar, sehingga akses API ditangguhkan. Faktur yang belum dibayar khusus untuk Social hanya menangguhkan endpoint Social. Lihat `payment_required` dan `social_payment_required`.	-	`APIError`
`403 Forbidden`	Kunci valid, tetapi tidak memiliki izin untuk mengakses sumber daya.	`SY90003`	`PermissionDeniedError`
`404 Not Found`	Path atau sumber daya yang dituju berdasarkan ID tidak ada.	`SY90002`	`NotFoundError`
`422 Unprocessable Entity`	Format permintaan sudah benar, tetapi ada nilai yang tidak dapat diproses (misalnya, kategori yang tidak dikenal atau ambigu).	-	`ValidationError`
`429 Too Many Requests`	Anda telah melampaui batas laju paket Anda. Patuhi header `Retry-After`.	-	`RateLimitError`
`5xx`	Kesalahan server. Operasi baca aman untuk dicoba kembali dengan jeda yang bertambah; lihat catatan kehati-hatian tentang operasi tulis di bawah sebelum mengulangi operasi tulis.	`SY90007`	`InternalServerError`

Tiga bentuk respons

Sebagian besar kegagalan menyertakan array errors, baik di tingkat teratas maupun di dalam hasil operasi, seperti yang ditunjukkan pada bagian-bagian di bawah. Beberapa kegagalan mengembalikan satu objek error sebagai gantinya: pembatasan laju (429) dan beberapa kegagalan tingkat permintaan (400/500 dengan code seperti INTERNAL_SERVER_ERROR). Periksa keduanya: errors adalah array, error adalah objek.

1. Tingkat permintaan: `errors[]` di tingkat teratas

Kegagalan autentikasi, otorisasi, dan format permintaan menghentikan pemrosesan sebelum operasi dijalankan. Kegagalan tersebut mengembalikan status 4xx yang sesuai (di atas) dengan kesalahan di tingkat teratas respons.

JSON

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. Validasi operasi tulis: `data.<operation>.errors[]` bersarang

Permintaan untuk membuat, memperbarui, atau memublikasikan yang secara umum berformat benar mengembalikan HTTP 200. Jika input melanggar aturan bisnis, kegagalan dilaporkan secara bersarang di bawah payload milik operasi itu sendiri dalam data.<operation>.errors. Jika berhasil, array ini ada dan kosong ("errors": []).

JSON

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. Tingkat gateway: satu objek `error` di tingkat teratas

Pembatasan laju dan gangguan gateway yang tidak terduga menghentikan pemrosesan sebelum penerjemahan dan mengembalikan satu objek error dengan code, message, dan correlation_id. Lihat rate_limited di bawah untuk isi respons 429.

Selalu baca data.<operation>.errors pada operasi tulis, bahkan pada respons 200 dengan objek data.<operation> yang terisi: operasi tulis dapat gagal sebagian dan melaporkannya di sini.

Respons 402 Payment Required tidak memiliki pembungkus error: code, message, doc_url dan, jika ada faktur yang harus dibayar, pay_url berada di tingkat teratas. Lihat payment_required di bawah.

Mengulangi operasi tulis memiliki konsekuensi

API v4 tidak mendukung Idempotency-Key: header tersebut diabaikan, dan tidak ada endpoint yang mendeteksi operasi tulis berulang. Panggilan untuk membuat, memperbarui, atau memublikasikan yang mengalami batas waktu atau mengembalikan 5xx mungkin tetap telah menyimpan perubahan di server, sehingga percobaan ulang tanpa pemeriksaan dapat menghasilkan duplikat lokasi, postingan, atau balasan ulasan.

Anda dapat mengulangi operasi baca dengan jeda yang bertambah. Untuk operasi tulis, baca kembali terlebih dahulu: cari rekaman berdasarkan kunci yang Anda kendalikan (storeId, kode toko, daftar respons interaksi) dan hanya ulangi panggilan jika rekaman tersebut benar-benar tidak ada.

Kode umum

Common SY error codes

Kode	Pesan	Status HTTP	Arti
`SY90005`	`Invalid Token`	`401`	Kunci API tidak disertakan, formatnya salah, atau telah dicabut. Terbitkan ulang kunci dari dasbor dan kirimkan sebagai `Authorization: API <your-key>`.
`SY90001`	`Not authorized to access this resource`	`401` / `403`	Kunci ditolak untuk sumber daya ini. SDK Python dan Node sama-sama memunculkan kesalahan ini sebagai `AuthenticationError`.
`SY90002`	`Invalid Id`	`404` / `400`	ID pada path atau argumen tidak dapat diidentifikasi (sering kali berupa ID relay yang tidak valid atau bukan dalam format base64).
`SY10126`	`City is Mandatory`	`200` (isi respons)	Field wajib (`city`) tidak disertakan dalam input.
`SY10010`	`state_iso`	`200` (isi respons)	Nilai `stateIso` tidak disertakan atau tidak valid. Lihat endpoint negara dan negara bagian untuk mengetahui nilai yang valid.

Kode validasi dalam rentang SY10xxx berkaitan dengan field input tertentu; message menyebutkan field atau aturan yang gagal dipenuhi. Kode autentikasi dan otorisasi dalam rentang SY90xxx berlaku pada tingkat permintaan dan dikembalikan di tingkat teratas dengan status yang sesuai.

Kode akun terhubung

Kode dalam rentang SY810xx berasal dari endpoint Connected Accounts yang mengimpor atau menautkan profil bisnis di platform publikasi. Kode tersebut dikembalikan secara bersarang dalam isi respons pada HTTP 200 (bentuk respons 2 di atas), jadi baca data.<operation>.errors meskipun statusnya menunjukkan keberhasilan.

SY810xx connected-account and import codes

Kode	Arti	Tindakan yang perlu dilakukan
`SY81019`	Tidak ada pengguna yang dapat diidentifikasi untuk akun yang terkait dengan kunci tersebut.	Hubungi dukungan: akun tidak memiliki pengguna utama yang aktif.
`SY81066`	`connectedAccountId` tidak ada, atau akun telah diarsipkan.	Baca ulang ID dari `GET /connected-accounts`.
`SY81067`	`connectedAccountListingId` tidak dapat didekode atau diidentifikasi.	Ambil ulang dari `id` pada record connected-account-listings.
`SY81068`	Profil bisnis tersebut sudah ditautkan ke suatu lokasi.	Putuskan tautannya terlebih dahulu, atau pilih profil bisnis lain.
`SY81069`	Kredensial akun terhubung tidak lagi valid.	Hubungkan kembali akun melalui connect-google atau connect-facebook.
`SY81070`	Profil bisnis tersebut bukan milik akun terhubung yang Anda sebutkan.	Pasangkan setiap profil bisnis dengan akun asalnya. Penyebab yang umum adalah mengambil profil bisnis tanpa `connectedAccountId` dalam isi permintaan, sehingga yang dikembalikan adalah profil bisnis milik akun lain.
`SY81071`	Terjadi kesalahan tak terduga saat membuat lokasi.	Coba lagi; jika masalah berlanjut, hubungi dukungan.
`SY81072`	Pembuatan lokasi gagal saat menyusun atau menyimpan data.	Coba lagi; jika masalah berlanjut, hubungi dukungan.
`SY81073`	Jenis profil bisnis ini tidak didukung untuk impor.	Hanya profil bisnis Google dan Facebook yang dapat diimpor.
`SY81074`	Google tidak mengembalikan data untuk profil bisnis tersebut.	Pastikan profil bisnis tersebut masih ada dan akun masih mengelolanya.
`SY81075`	Batas laju permintaan API Google terlampaui.	Coba lagi nanti dengan jeda yang bertambah secara bertahap.
`SY81076`	Pengambilan profil bisnis dari Google gagal.	Coba lagi; periksa izin Google untuk akun tersebut.
`SY81077`	Negara tidak dapat ditentukan dari halaman Facebook.	Tambahkan negara ke alamat halaman di Facebook, lalu coba lagi.
`SY81078`	Penyusunan data lokasi dari halaman Facebook gagal.	Coba lagi; jika masalah berlanjut, hubungi dukungan.
`SY81081`	Profil bisnis belum memiliki kategori utama yang ditetapkan.	Tetapkan kategori utama pada profil bisnis, lalu coba lagi.
`SY81082`	Negara profil bisnis tidak didukung.	Lihat endpoint negara dan negara bagian untuk mengetahui negara yang didukung.
`SY81083`	Profil bisnis Google tidak dapat diimpor.	Hubungi dukungan dengan menyertakan waktu kejadian.
`SY81084`	Terjadi kesalahan internal saat menyiapkan impor Facebook.	Coba lagi; jika masalah berlanjut, hubungi dukungan dengan menyertakan waktu kejadian.
`SY81085`	Halaman Facebook tidak dapat diimpor.	Hubungi dukungan dengan menyertakan waktu kejadian.
`SY81086`	Pembuatan lokasi ditolak oleh aturan bisnis. `message` yang bersarang memuat kode penyebabnya, misalnya `SY10151` saat akun kehabisan kuota lokasi.	Baca pesan yang bersarang; untuk `SY10151`, tambahkan add-on lokasi atau tingkatkan paket.
`SY81087`	Permintaan pembuatan lokasi gagal.	Coba lagi; jika masalah berlanjut, hubungi dukungan dengan menyertakan waktu kejadian.
`SY81088`	Pembuatan lokasi gagal karena alasan yang tidak dikenali.	Hubungi dukungan dengan menyertakan waktu kejadian.
`SY81089`	Panggilan layanan internal mengembalikan status yang tidak menunjukkan keberhasilan. Ini bukan masalah pada permintaan Anda.	Coba lagi satu kali; jika masalah berlanjut, hubungi dukungan dengan menyertakan waktu kejadian agar kami dapat melacak panggilan internal tersebut.
`SY81090`	Terjadi kesalahan tak terduga selama panggilan internal untuk pembuatan lokasi.	Coba lagi; jika masalah berlanjut, hubungi dukungan dengan menyertakan waktu kejadian.

Kode dalam rentang SY950xx berasal dari endpoint Social: merek, koneksi, dan postingan media sosial. Seperti kode akun terhubung, kode ini muncul secara bertingkat di dalam isi respons pada HTTP 200, jadi baca data.<operation>.error (dan data.<operation>.errors pada rute massal) meskipun statusnya menunjukkan keberhasilan.

SY950xx Social codes

Kode	Arti	Tindakan yang perlu dilakukan
`SY95041`	Akun telah mencapai batas jumlah mereknya. Tidak dapat terjadi pada paket API: jumlah merek tidak dibatasi pada paket tersebut.	Tidak ada tindakan yang perlu dilakukan pada paket API. Jika Anda melihatnya, laporkan: `GET /social/limits` seharusnya mengembalikan `brands: null`.
`SY95042`	Akun telah mencapai batas jumlah koneksi untuk periode penagihan saat ini.	Batas tersebut dibandingkan dengan `usage.connections` dari `GET /social/limits` — jumlah yang dikenakan biaya: koneksi yang terhubung saat ini ditambah koneksi yang dilepas selama periode ini. Slot yang dibebaskan dengan memutuskan koneksi atau dengan mengarsipkan merek tetap dicadangkan hingga periode berakhir, sehingga pemutusan koneksi baru-baru ini tidak mengatasi kesalahan ini. Hubungkan kembali salah satu akun yang Anda lepas ke merek tempat akun tersebut sebelumnya terhubung (gratis, menggunakan kembali slot tersebut), beli paket tambahan berisi 5 koneksi (langsung tersedia), atau tunggu perpanjangan, saat slot `usage.connectionsReleased` kembali tersedia. Menghubungkan akun yang telah dilepas ke merek lain tidak menggunakan kembali slot tersebut. Lihat Paket dan add-on.
`SY95043`	Tidak ada merek dengan ID tersebut pada akun ini, atau merek tersebut telah diarsipkan.	Baca kembali ID dari `GET /social/brands`. ID merek berupa UUID biasa, bukan ID relay Base64.
`SY95044`	Platform tersebut tidak diaktifkan untuk akun ini.	Paket Social akun ini tidak mencakup platform yang Anda minta untuk dihubungkan. Hubungi dukungan atau pilih platform yang tersedia untuk akun ini.
`SY95045`	Merek ini tidak memiliki kanal yang terhubung untuk platform tersebut.	Arahkan pengguna melalui tautan koneksi untuk platform tersebut, atau hapus platform tersebut dari `platforms`. Kesalahan ini juga muncul ketika koneksi kanal diputus setelah postingan dijadwalkan.
`SY95046`	Jadwal atau zona waktu tidak valid.	Kirim `scheduledAt` atau `scheduleDate` + `scheduleTime`, jangan pernah keduanya. `scheduledAt` memerlukan offset UTC; `scheduleTime` adalah `HH:MM`. Zona waktu menggunakan pengenal IANA (`tzCode`).
`SY95047`	Tidak ada tugas massal dengan ID tersebut pada akun ini.	Baca kembali `job.id` dari respons pembuatan massal. Tugas tidak disimpan selamanya.
`SY95048`	Permintaan massal melebihi batas jumlah baris.	Kirim paling banyak 500 baris per permintaan dan bagi sisanya ke dalam kelompok berikutnya. Tidak ada yang dibuat.
`SY95049`	URL pengalihan tidak valid.	`redirectUrl` dan `errorUrl` pada tautan koneksi harus berupa URL `https` absolut yang Anda kendalikan.
`SY95050`	Validasi massal gagal; lihat kesalahan per baris.	Tidak ada yang dibuat. Baca `job.results[]`: setiap baris yang ditolak memuat `index` yang dihitung mulai dari 0, `clientReference`, dan alasannya dalam `errors[]`. Perbaiki baris-baris tersebut dan kirim ulang seluruh kelompok.
`SY95051`	Merek belum memenuhi persyaratan masa keberadaan 90 hari.	Merek tidak dapat diarsipkan sebelum berusia 90 hari. Respons juga melaporkan `status: "TENURE_NOT_MET"` dan tidak ada yang berubah. Coba lagi setelah hari ke-90, saat merek dan koneksinya langsung diarsipkan — meskipun slot koneksinya tetap dicadangkan hingga akhir periode penagihan. Lihat aturan masa keberadaan.
`SY95052`	Kanal yang terhubung bukan milik merek ini.	Pasangkan setiap koneksi dengan merek tempat koneksi tersebut dibuat. Kesalahan ini umum terjadi ketika panggilan insights dibuat menggunakan postingan dari satu merek dan ID kanal dari merek lain.

SY95042 dan SY95044 merupakan kegagalan akibat hak akses paket, bukan kesalahan input: mencoba kembali tanpa mengubah paket akan menghasilkan kegagalan yang sama. SY95045, SY95046, SY95049, dan SY95052 merupakan kesalahan input yang dapat diperbaiki pada permintaan berikutnya.

Kode hak akses Listings

Listings plan codes

Kode	Arti	Tindakan yang perlu dilakukan
`SY10150`	Akun telah mencapai batas jumlah lokasi.	Arsipkan lokasi, beli add-on lokasi tambahan, atau tingkatkan paket. Lihat Paket dan add-on.
`SY10151`	Akun tidak memiliki sisa kuota lokasi pada paket ini. Pada akses harian sandbox, kedua lokasinya sudah digunakan.	Langkah penanganannya sama seperti `SY10150`. Pada akses harian, perbarui lokasi yang sudah ada atau pilih paket berbayar. Kode ini juga muncul secara bersarang di dalam `SY81086` saat lokasi dibuat dari profil bisnis akun yang terhubung.
`SY10152`	Lokasi belum aktif cukup lama untuk dapat diarsipkan.	Lokasi harus aktif selama masa aktif minimum yang ditetapkan untuk akun, yaitu 90 hari secara default, sebelum `POST /locations/archive` dapat menerimanya. Tunggu hingga masa aktif minimum tersebut terpenuhi.
`SY10155`	Akun tidak memiliki paket Listings, sehingga lokasi tidak dapat dibuat.	Kunci API tersebut milik akun tanpa langganan Listings, seperti akun yang hanya berlangganan Social. Lokasi merupakan bagian dari produk Listings; berlanggananlah produk tersebut sebelum memanggil `POST /locations`.

`rate_limited`

429 Too Many Requests: akun melampaui batas laju permintaan paketnya. Isi respons merupakan respons kesalahan standar yang memuat petunjuk retry_after_seconds, correlation_id untuk dicantumkan dalam permintaan dukungan, dan doc_url yang menautkan kembali ke bagian ini:

JSON

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Tunggu sesuai retry_after_seconds (atau header Retry-After jika tersedia), lalu coba lagi dengan jeda yang bertambah secara eksponensial. Lihat Batas laju permintaan untuk batas tiap paket dan contoh implementasi jeda percobaan ulang.

`payment_required`

402: Pembayaran terakhir untuk akun ini gagal, sehingga setiap endpoint /api/v4 dinonaktifkan sementara. Isi respons menyertakan pay_url, yaitu halaman Stripe untuk faktur yang belum dibayar, jika tersedia, dan header respons X-Error-Code memuat code yang sama. Anda masih dapat membuka halaman Penagihan di dasbor untuk membayar.

JSON

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

Akses dipulihkan dalam satu menit setelah faktur terbuka terakhir dibayar. Jika faktur masih belum dibayar 3 hari setelah kegagalan pembayaran pertama, langganan Listings dibatalkan dan lokasi milik akun diarsipkan. Jika akun juga memiliki langganan Social yang aktif, akun tetap memiliki akses Social; jika tidak, akun ditutup dan kunci API-nya berhenti berfungsi.

`social_payment_required`

402: Pembayaran terakhir untuk langganan Social gagal, sehingga endpoint Social (/api/v4/social/*) dinonaktifkan sementara. Endpoint Listings tetap berfungsi. Isi respons memiliki field yang sama dengan payment_required, dengan "code": "social_payment_required". Jika faktur masih belum dibayar 3 hari setelah kegagalan pembayaran pertama, langganan Social dibatalkan dan merek milik akun diarsipkan. Akun tanpa langganan Listings ditutup, dan kunci API-nya berhenti berfungsi.

Kesalahan bidang kontrol portal pengembang

Endpoint pengelolaan akun dan kunci di portal pengembang (rute API milik dasbor sendiri) mengembalikan satu respons kesalahan terstruktur yang berbeda dari format REST errors[] di atas. Setiap code memuat correlation_id dan doc_url yang menautkan kembali ke bagian yang sesuai di sini.

JSON

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

`auth_missing_key`

401: Tidak ada kredensial yang diberikan. Masuk kembali, atau kirim kunci Anda sebagai Authorization: API <your-key>.

`auth_invalid_key`

401: Sesi atau kunci tidak valid atau telah kedaluwarsa. Lakukan autentikasi ulang atau terbitkan ulang kunci dari dasbor.

`auth_insufficient_scope`

403: Kredensial valid tetapi tidak diizinkan untuk tindakan ini. Kunci dengan cakupan baca tidak dapat memanggil endpoint tulis; terbitkan kunci dengan izin tulis jika Anda membutuhkannya.

`not_found`

404: Sumber daya yang diminta, atau sumber daya yang dirujuk berdasarkan ID, tidak ada.

`conflict`

409: Permintaan bertentangan dengan status sumber daya saat ini (misalnya, mencabut kunci yang sudah dicabut).

`validation_failed`

422: Isi permintaan gagal dalam validasi. field dan details dalam respons menyebutkan input yang bermasalah.

`internal_error`

500: Kesalahan tak terduga di sisi server. Coba ulang operasi baca dengan jeda yang bertambah secara eksponensial; untuk operasi tulis, baca kembali rekaman terlebih dahulu (lihat Mencoba ulang operasi tulis memiliki konsekuensi). Cantumkan correlation_id jika Anda menghubungi dukungan.

`dependency_unavailable`

503: Layanan yang menjadi dependensi API sedang tidak tersedia. Coba lagi dengan jeda percobaan ulang.

Untuk 429, lihat rate_limited di atas.

Menangani kesalahan dalam kode

Periksa status HTTP terlebih dahulu; lalu, untuk operasi tulis, telusuri isi respons untuk menemukan array errors bersarang:

Python

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

Saat menggunakan API HTTP secara langsung, dua pemeriksaan yang sama dilakukan secara eksplisit: kode status, lalu payload respons:

Python

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

Python SDK melakukan keduanya untuk Anda: SDK ini memetakan setiap status HTTP ke pengecualian dengan tipe tertentu dan juga memunculkan pengecualian saat payload kesalahan dikembalikan di dalam isi 200.