Errori e paginazione #

Questa pagina tratta due aspetti che ogni integrazione deve gestire: come appare una richiesta fallita e come scorrere gli endpoint che restituiscono elenchi.

Il formato dell’errore #

Quando una richiesta fallisce, la risposta è sempre in formato JSON con la stessa struttura: un flag success impostato su false, un messaggio error leggibile dall’utente e un error_code numerico che corrisponde allo stato HTTP:

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

Poiché success e error_code sono sempre presenti, è possibile basare la logica su di essi senza dover esaminare i codici di stato HTTP non elaborati, se lo si preferisce. Una risposta corretta ha sempre success: true.

Codici di stato #

Alcuni esempi di come appaiono nella pratica:

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

Gestire correttamente gli errori #

• Controlla success (o il codice di stato) prima di leggere i dati. Non dare per scontato che il corpo della risposta contenga il campo che ti aspetti.
• Riprova 429 e 500 con un breve back-off: attendi, poi riprova. Non riprovare 400, 401, 403, 404 o 409; continueranno a fallire finché non modificherai la richiesta.
• Leggi il messaggio error. Di solito indica esattamente quale campo è errato.

Paginazione #

Gli endpoint di elenco (come GET /contacts, GET /campaigns e GET /tasks) restituiscono i risultati in pagine, in modo che una singola chiamata non debba mai caricare l’intero account. La paginazione utilizza un cursore opaco.

Due parametri di query la controllano:

Ogni pagina include un campo next_cursor nella risposta:

• Se next_cursor è una stringa, ci sono altri risultati: passala come cursor nella tua prossima richiesta.
• Se next_cursor è null, hai raggiunto l’ultima pagina. Fermati.

Una singola pagina di contatti appare così:

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

Navigazione tra tutti i contatti #

Per raccogliere un intero elenco, inizia senza cursore e continua a chiamare finché next_cursor non restituisce null.

cURL

Questo esempio scorre manualmente le prime due pagine. Esegui la prima chiamata, copia il next_cursor dalla sua risposta in CURSOR, quindi esegui la seconda chiamata. Ripeti finché next_cursor non è 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

Lo stesso ciclo funziona per qualsiasi endpoint paginato: basta cambiare il percorso e il campo letto dalla risposta (campaigns, tasks e così via).

Passaggi successivi #

• Autenticazione — i quattro modi per inviare la tua chiave.
• Contatti — gli endpoint completi dei contatti utilizzati negli esempi sopra.
• Chiavi API — controlla l’utilizzo del limite di frequenza in tempo reale per evitare 429.