Fejl & Sidetal #

Denne side dækker to ting, som enhver integration skal håndtere: hvordan en mislykket anmodning ser ud, og hvordan man navigerer gennem slutpunkter, der returnerer lister.

Fejl-konvolutten #

Når en anmodning mislykkes, er svaret altid JSON med samme form — et success-flag sat til false, en læsbar error-besked og en numerisk error_code, der matcher HTTP-statuskoden:

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

Da success og error_code altid er til stede, kan du forgrene din logik baseret på dem uden at skulle inspicere rå HTTP-statuskoder, hvis du foretrækker det. Et vellykket svar har altid success: true.

Statuskoder #

Et par eksempler på, hvordan disse ser ud i praksis:

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

Håndtering af fejl #

• Tjek success (eller statuskoden), før du læser data. Gå ikke ud fra, at en svartekst indeholder det felt, du forventer.
• Prøv 429 og 500 igen med en kort forsinkelse — vent, og prøv derefter igen. Prøv ikke 400, 401, 403, 404 eller 409 igen; de vil fortsat fejle, indtil du ændrer anmodningen.
• Læs error-beskeden. Den fortæller dig normalt præcis, hvilket felt der er forkert.

Sidetal (Pagination) #

Listeslutpunkter (såsom GET /contacts, GET /campaigns og GET /tasks) returnerer resultater i sider, så et enkelt kald aldrig behøver at indlæse hele din konto. Sidetal bruger en uigennemsigtig markør (cursor).

To forespørgselsparametre styrer dette:

Hver side inkluderer et next_cursor-felt i svaret:

• Hvis next_cursor er en streng, er der flere resultater — send den som cursor i din næste anmodning.
• Hvis next_cursor er null, har du nået den sidste side. Stop.

En enkelt side med kontakter ser således ud:

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

Gennemgang af alle kontakter #

For at indsamle en komplet liste skal du starte uden en markør og fortsætte med at kalde, indtil next_cursor returneres som null.

cURL

Dette eksempel gennemgår de første to sider manuelt. Kør det første kald, kopier next_cursor fra svaret ind i CURSOR, og kør derefter det andet kald. Gentag indtil next_cursor er 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

Den samme løkke fungerer for ethvert pagineret slutpunkt — du skal blot ændre stien og det felt, du læser fra svaret (campaigns, tasks og så videre).

Næste skridt #

• Godkendelse — de fire måder at sende din nøgle på.
• Kontakter — de fulde kontakt-slutpunkter, der bruges i eksemplerne ovenfor.
• API-nøgler — tjek dit aktuelle forbrug af hastighedsbegrænsning for at undgå 429.