Fel & sidindelning #

Den här sidan täcker två saker som varje integration behöver hantera: hur en misslyckad förfrågan ser ut och hur man bläddrar igenom slutpunkter som returnerar listor.

Felmeddelande-kuvertet #

När en förfrågan misslyckas är svaret alltid JSON med samma struktur — en success-flagga satt till false, ett läsbart error-meddelande och en numerisk error_code som matchar HTTP-statusen:

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

Eftersom success och error_code alltid finns med kan du förgrena logiken baserat på dem utan att behöva inspektera råa HTTP-statuskoder om du föredrar det. Ett lyckat svar har alltid success: true.

Statuskoder #

Några exempel på hur dessa ser ut i praktiken:

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

Hantera fel på ett bra sätt #

• Kontrollera success (eller statuskoden) innan du läser data. Anta inte att en svarstext innehåller det fält du förväntar dig.
• Försök igen vid 429 och 500 med en kort fördröjning — vänta, försök sedan igen. Försök inte igen vid 400, 401, 403, 404 eller 409; dessa kommer att fortsätta misslyckas tills du ändrar förfrågan.
• Läs error-meddelandet. Det talar oftast om exakt vilket fält som är felaktigt.

Sidindelning #

List-slutpunkter (såsom GET /contacts, GET /campaigns och GET /tasks) returnerar resultat i sidor så att ett enskilt anrop aldrig behöver läsa in hela ditt konto. Sidindelning använder en ogenomskinlig markör (cursor).

Två frågeparametrar styr detta:

Varje sida inkluderar ett next_cursor-fält i svaret:

• Om next_cursor är en sträng finns det fler resultat — skicka med den som cursor i din nästa förfrågan.
• Om next_cursor är null har du nått den sista sidan. Stoppa.

En enskild sida med kontakter ser ut så här:

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

Bläddra igenom alla kontakter #

För att hämta en hel lista, börja utan markör och fortsätt anropa tills next_cursor returneras som null.

cURL

Det här exemplet går igenom de två första sidorna manuellt. Kör det första anropet, kopiera next_cursor från svaret till CURSOR, och kör sedan det andra anropet. Upprepa tills next_cursor är 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

Samma loop fungerar för alla paginerade slutpunkter — ändra bara sökvägen och fältet du läser från svaret (campaigns, tasks, och så vidare).

Nästa steg #

• Autentisering — de fyra sätten att skicka din nyckel.
• Kontakter — de fullständiga kontaktslutpunkterna som används i exemplen ovan.
• API-nycklar — kontrollera din nuvarande användning av hastighetsbegränsningar för att undvika 429.