Błędy i stronicowanie #

Ta strona omawia dwie rzeczy, z którymi musi radzić sobie każda integracja: jak wygląda nieudane żądanie oraz jak poruszać się po punktach końcowych zwracających listy.

Koperta błędu #

Gdy żądanie kończy się niepowodzeniem, odpowiedź zawsze ma postać JSON o tym samym kształcie — flaga success ustawiona na false, czytelny dla człowieka komunikat error oraz numeryczny error_code odpowiadający kodowi statusu HTTP:

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

Ponieważ success i error_code są zawsze obecne, możesz na ich podstawie rozgałęziać logikę bez konieczności sprawdzania surowych kodów statusu HTTP, jeśli wolisz. Pomyślna odpowiedź zawsze zawiera success: true.

Kody statusu #

Kilka przykładów tego, jak wygląda to w praktyce:

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

Prawidłowa obsługa błędów #

• Sprawdź success (lub kod statusu) przed odczytaniem danych. Nie zakładaj, że treść odpowiedzi zawiera oczekiwane pole.
• Ponawiaj żądania 429 i 500 z krótkim opóźnieniem — odczekaj, a następnie spróbuj ponownie. Nie ponawiaj żądań 400, 401, 403, 404 lub 409; będą one nadal kończyć się niepowodzeniem, dopóki nie zmienisz żądania.
• Przeczytaj komunikat error. Zazwyczaj informuje on dokładnie, które pole jest błędne.

Stronicowanie #

Punkty końcowe list (takie jak GET /contacts, GET /campaigns i GET /tasks) zwracają wyniki na stronach, dzięki czemu pojedyncze wywołanie nigdy nie musi ładować całego Twojego konta. Stronicowanie wykorzystuje nieprzejrzysty kursor.

Kontrolują to dwa parametry zapytania:

Każda strona zawiera pole next_cursor w odpowiedzi:

• Jeśli next_cursor jest ciągiem znaków, istnieją kolejne wyniki — przekaż go jako cursor w następnym żądaniu.
• Jeśli next_cursor to null, dotarłeś do ostatniej strony. Zatrzymaj się.

Pojedyncza strona kontaktów wygląda następująco:

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

Przeglądanie wszystkich kontaktów #

Aby pobrać pełną listę, zacznij bez kursora i wywołuj żądania, dopóki next_cursor nie zwróci null.

cURL

Ten przykład ręcznie przechodzi przez pierwsze dwie strony. Wykonaj pierwsze wywołanie, skopiuj next_cursor z odpowiedzi do CURSOR, a następnie wykonaj drugie wywołanie. Powtarzaj, aż next_cursor będzie równe 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

Ta sama pętla działa dla każdego stronicowanego punktu końcowego — wystarczy zmienić ścieżkę i pole odczytywane z odpowiedzi (campaigns, tasks itd.).

Następne kroki #

• Uwierzytelnianie — cztery sposoby przesyłania klucza.
• Kontakty — pełne punkty końcowe kontaktów użyte w powyższych przykładach.
• Klucze API — sprawdź bieżące wykorzystanie limitu szybkości, aby uniknąć 429.