Error & Penomoran Halaman #

Halaman ini membahas dua hal yang perlu ditangani oleh setiap integrasi: seperti apa bentuk permintaan yang gagal, dan cara melakukan penomoran halaman melalui endpoint yang mengembalikan daftar.

Amplop error #

Saat permintaan gagal, responsnya selalu berupa JSON dengan bentuk yang sama — flag success yang disetel ke false, pesan error yang dapat dibaca manusia, dan error_code numerik yang sesuai dengan status HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Karena success dan error_code selalu ada, Anda dapat melakukan percabangan berdasarkan keduanya tanpa perlu memeriksa kode status HTTP mentah jika Anda mau. Respons yang berhasil selalu memiliki success: true.

Kode status #

Beberapa contoh bagaimana bentuknya dalam praktiknya:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

{
  "success": false,
  "error": "A contact with this phone number already exists",
  "error_code": 409
}

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Menangani error dengan baik #

• Periksa success (atau kode status) sebelum membaca data. Jangan berasumsi bahwa isi respons memiliki kolom yang Anda harapkan.
• Coba lagi 429 dan 500 dengan jeda singkat — tunggu, lalu coba lagi. Jangan coba lagi 400, 401, 403, 404, atau 409; permintaan tersebut akan terus gagal sampai Anda mengubah permintaannya.
• Baca pesan error. Pesan tersebut biasanya memberi tahu Anda dengan tepat kolom mana yang salah.

Penomoran halaman #

Endpoint daftar (seperti GET /contacts, GET /campaigns, dan GET /tasks) mengembalikan hasil dalam halaman sehingga satu panggilan tidak perlu memuat seluruh akun Anda. Penomoran halaman menggunakan kursor buram (opaque cursor).

Dua parameter kueri mengendalikannya:

Setiap halaman menyertakan kolom next_cursor dalam respons:

• Jika next_cursor adalah string, berarti masih ada hasil lainnya — teruskan sebagai cursor pada permintaan Anda berikutnya.
• Jika next_cursor adalah null, Anda telah mencapai halaman terakhir. Berhenti.

Satu halaman kontak terlihat seperti ini:

{
  "success": true,
  "contacts": [
    { "id": "abc123", "first_name": "Jane", "phone_number": "+15551234567" },
    { "id": "def456", "first_name": "John", "phone_number": "+15557654321" }
  ],
  "next_cursor": "eyJsYXN0IjoiZGVmNDU2In0"
}

Menelusuri semua kontak #

Untuk mengumpulkan seluruh daftar, mulailah tanpa kursor dan terus lakukan panggilan hingga next_cursor kembali menjadi null.

cURL

Contoh ini menelusuri dua halaman pertama secara manual. Jalankan panggilan pertama, salin next_cursor dari responsnya ke dalam CURSOR, lalu jalankan panggilan kedua. Ulangi hingga next_cursor menjadi null.

# First page
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY&limit=100"

# Next page — paste the next_cursor from the previous response
CURSOR="eyJsYXN0IjoiZGVmNDU2In0"
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY&limit=100&cursor=$CURSOR"

JavaScript

async function getAllContacts() {
  const all = [];
  let cursor = null;

  do {
    const url = new URL("https://api.youraiconnector.com/v1/contacts");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { "X-API-Key": "YOUR_API_KEY" },
    });
    const data = await res.json();

    if (!data.success) throw new Error(data.error);

    all.push(...data.contacts);
    cursor = data.next_cursor;
  } while (cursor);

  return all;
}

Python

import requests

def get_all_contacts():
    all_contacts = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

        res = requests.get(
            "https://api.youraiconnector.com/v1/contacts",
            params=params,
            headers={"X-API-Key": "YOUR_API_KEY"},
        )
        data = res.json()

        if not data["success"]:
            raise Exception(data["error"])

        all_contacts.extend(data["contacts"])
        cursor = data["next_cursor"]

        if not cursor:
            break

    return all_contacts

Loop yang sama berfungsi untuk endpoint terpaginasi mana pun — cukup ubah path dan field yang Anda baca dari respons (campaigns, tasks, dan seterusnya).

Langkah berikutnya #

• Autentikasi — empat cara untuk mengirim kunci Anda.
• Kontak — endpoint kontak lengkap yang digunakan dalam contoh di atas.
• Kunci API — periksa penggunaan batas kecepatan (rate-limit) langsung Anda untuk menghindari 429.