Fehler & Paginierung #

Diese Seite behandelt zwei Dinge, die jede Integration berücksichtigen muss: wie eine fehlgeschlagene Anfrage aussieht und wie man durch Endpunkte blättert, die Listen zurückgeben.

Das Fehler-Envelope #

Wenn eine Anfrage fehlschlägt, ist die Antwort immer ein JSON-Objekt mit der gleichen Struktur – ein success-Flag, das auf false gesetzt ist, eine für Menschen lesbare error-Nachricht und ein numerischer error_code-Wert, der dem HTTP-Status entspricht:

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

Da success und error_code immer vorhanden sind, können Sie diese zur Fallunterscheidung nutzen, ohne die rohen HTTP-Statuscodes prüfen zu müssen, falls Sie dies bevorzugen. Eine erfolgreiche Antwort enthält immer success: true.

Statuscodes #

Ein paar Beispiele, wie diese in der Praxis aussehen:

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

Fehler richtig behandeln #

• Prüfen Sie success (oder den Statuscode), bevor Sie Daten lesen. Gehen Sie nicht davon aus, dass ein Antwort-Body das von Ihnen erwartete Feld enthält.
• Wiederholen Sie 429 und 500 mit einer kurzen Verzögerung – warten Sie und versuchen Sie es dann erneut. Wiederholen Sie nicht 400, 401, 403, 404 oder 409; diese werden weiterhin fehlschlagen, bis Sie die Anfrage ändern.
• Lesen Sie die error-Nachricht. Sie sagt Ihnen normalerweise genau, welches Feld falsch ist.

Paginierung #

Listen-Endpunkte (wie GET /contacts, GET /campaigns und GET /tasks) geben Ergebnisse in Seiten zurück, sodass ein einzelner Aufruf niemals Ihr gesamtes Konto laden muss. Die Paginierung verwendet einen opaken Cursor.

Zwei Abfrageparameter steuern dies:

Jede Seite enthält ein next_cursor-Feld in der Antwort:

• Wenn next_cursor ein String ist, gibt es weitere Ergebnisse – übergeben Sie diesen als cursor bei Ihrer nächsten Anfrage.
• Wenn next_cursor null ist, haben Sie die letzte Seite erreicht. Stoppen Sie.

Eine einzelne Seite mit Kontakten sieht so aus:

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

Alle Kontakte durchblättern #

Um eine vollständige Liste zu erfassen, beginnen Sie ohne Cursor und rufen Sie die Seite so lange auf, bis next_cursor als null zurückgegeben wird.

cURL

Dieses Beispiel geht die ersten beiden Seiten manuell durch. Führen Sie den ersten Aufruf aus, kopieren Sie den next_cursor aus der Antwort in CURSOR und führen Sie dann den zweiten Aufruf aus. Wiederholen Sie dies, bis next_cursor gleich null ist.

# 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

Die gleiche Schleife funktioniert für jeden paginierten Endpunkt – ändern Sie einfach den Pfad und das Feld, das Sie aus der Antwort lesen (campaigns, tasks usw.).

Nächste Schritte #

• Authentifizierung – die vier Möglichkeiten, Ihren Schlüssel zu senden.
• Kontakte – die vollständigen Kontakt-Endpunkte, die in den obigen Beispielen verwendet werden.
• API-Schlüssel – überprüfen Sie Ihre aktuelle Ratenbegrenzung, um 429s zu vermeiden.