Hatalar ve Sayfalandırma #

Bu sayfa, her entegrasyonun ele alması gereken iki konuyu kapsar: başarısız bir isteğin nasıl göründüğü ve liste döndüren uç noktalar arasında nasıl sayfalandırma yapılacağı.

Hata zarfı #

Bir istek başarısız olduğunda, yanıt her zaman aynı biçime sahip bir JSON olur: false olarak ayarlanmış bir success bayrağı, insan tarafından okunabilir bir error mesajı ve HTTP durum koduyla eşleşen sayısal bir error_code:

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

success ve error_code her zaman mevcut olduğundan, isterseniz ham HTTP durum kodlarını incelemek yerine bunlar üzerinden dallanma yapabilirsiniz. Başarılı bir yanıt her zaman success: true içerir.

Durum kodları #

Bunların pratikte nasıl göründüğüne dair birkaç örnek:

{
  "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."
}

Hataları iyi yönetmek #

• Verileri okumadan önce success (veya durum kodunu) kontrol edin. Yanıt gövdesinin beklediğiniz alanı içerdiğini varsaymayın.
• 429 ve 500 hatalarını kısa bir bekleme süresiyle tekrar deneyin — bekleyin, sonra tekrar deneyin. 400, 401, 403, 404 veya 409 hatalarını tekrar denemeyin; bunlar siz isteği değiştirene kadar başarısız olmaya devam edecektir.
• error mesajını okuyun. Genellikle hangi alanın yanlış olduğunu size tam olarak söyler.

Sayfalandırma #

Liste uç noktaları (örneğin GET /contacts, GET /campaigns ve GET /tasks), sonuçları sayfalar halinde döndürür, böylece tek bir çağrı tüm hesabınızı yüklemek zorunda kalmaz. Sayfalandırma, opak bir imleç (cursor) kullanır.

Bunu iki sorgu parametresi kontrol eder:

Her sayfa, yanıtta bir next_cursor alanı içerir:

• Eğer next_cursor bir dizgiyse, daha fazla sonuç var demektir — bir sonraki isteğinizde bunu cursor olarak iletin.
• Eğer next_cursor değeri null ise, son sayfaya ulaştınız demektir. Durun.

Tek bir kişi sayfası şu şekilde görünür:

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

Tüm kişiler arasında gezinme #

Listenin tamamını toplamak için imleç olmadan başlayın ve next_cursor değeri null olarak dönene kadar çağırmaya devam edin.

cURL

Bu örnek, ilk iki sayfayı manuel olarak gezer. İlk çağrıyı çalıştırın, yanıtından gelen next_cursor değerini kopyalayıp CURSOR içine yerleştirin, ardından ikinci çağrıyı çalıştırın. next_cursor değeri null olana kadar tekrarlayın.

# 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

Aynı döngü tüm sayfalandırılmış uç noktalar için çalışır — sadece yolu ve yanıttan okuduğunuz alanı (campaigns, tasks vb.) değiştirin.

Sonraki adımlar #

• Kimlik Doğrulama — anahtarınızı göndermenin dört yolu.
• Kişiler — yukarıdaki örneklerde kullanılan tam kişi uç noktaları.
• API Anahtarları — 429 hatalarından kaçınmak için canlı hız sınırı kullanımınızı kontrol edin.