Fouten & Paginering #

Deze pagina behandelt twee zaken die elke integratie moet afhandelen: hoe een mislukt verzoek eruitziet en hoe je door eindpunten bladert die lijsten retourneren.

De fouten-envelop #

Wanneer een verzoek mislukt, is het antwoord altijd JSON met dezelfde vorm — een success-vlag ingesteld op false, een leesbaar error-bericht en een numerieke error_code die overeenkomt met de HTTP-status:

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

Omdat success en error_code altijd aanwezig zijn, kun je hierop vertakken zonder de ruwe HTTP-statuscodes te hoeven inspecteren als je dat wilt. Een succesvol antwoord heeft altijd success: true.

Statuscodes #

Een paar voorbeelden van hoe dit er in de praktijk uitziet:

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

Fouten goed afhandelen #

• Controleer success (of de statuscode) voordat je gegevens leest. Ga er niet vanuit dat een antwoordtekst het veld bevat dat je verwacht.
• Probeer 429 en 500 opnieuw met een korte wachttijd — wacht even en probeer het dan opnieuw. Probeer 400, 401, 403, 404 of 409 niet opnieuw; deze zullen blijven mislukken totdat je het verzoek wijzigt.
• Lees het error-bericht. Dit vertelt je meestal precies welk veld onjuist is.

Paginering #

Lijst-eindpunten (zoals GET /contacts, GET /campaigns en GET /tasks) retourneren resultaten in pagina’s, zodat een enkele aanroep nooit je hele account hoeft te laden. Paginering maakt gebruik van een ondoorzichtige cursor.

Twee queryparameters bepalen dit:

Elke pagina bevat een next_cursor-veld in het antwoord:

• Als next_cursor een string is, zijn er meer resultaten — geef deze door als de cursor bij je volgende aanvraag.
• Als next_cursor null is, heb je de laatste pagina bereikt. Stop.

Een enkele pagina met contactpersonen ziet er als volgt uit:

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

Door alle contactpersonen bladeren #

Om een volledige lijst te verzamelen, begin je zonder cursor en blijf je aanroepen totdat next_cursor terugkomt als null.

cURL

Dit voorbeeld doorloopt handmatig de eerste twee pagina’s. Voer de eerste aanroep uit, kopieer de next_cursor uit de reactie naar CURSOR en voer vervolgens de tweede aanroep uit. Herhaal dit totdat next_cursor gelijk is aan 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

Dezelfde lus werkt voor elk gepagineerd eindpunt — verander simpelweg het pad en het veld dat je uit de reactie leest (campaigns, tasks, enzovoort).

Volgende stappen #

• Authenticatie — de vier manieren om je sleutel te verzenden.
• Contactpersonen — de volledige contactpersoon-eindpunten die in de bovenstaande voorbeelden worden gebruikt.
• API-sleutels — controleer je actuele gebruik van de snelheidslimiet om 429s te voorkomen.