Erori și paginare #

Această pagină acoperă două aspecte pe care orice integrare trebuie să le gestioneze: cum arată o cerere eșuată și cum se poate naviga prin paginile punctelor terminale (endpoints) care returnează liste.

Anvelopa de eroare #

Când o cerere eșuează, răspunsul este întotdeauna un JSON cu aceeași formă — un indicator success setat pe false, un mesaj error lizibil pentru oameni și un error_code numeric care corespunde codului de stare HTTP:

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

Deoarece success și error_code sunt întotdeauna prezente, puteți crea ramificații pe baza lor fără a inspecta codurile de stare HTTP brute, dacă preferați. Un răspuns reușit are întotdeauna success: true.

Coduri de stare #

Câteva exemple despre cum arată acestea în practică:

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

Gestionarea corectă a erorilor #

• Verificați success (sau codul de stare) înainte de a citi datele. Nu presupuneți că un corp de răspuns conține câmpul pe care îl așteptați.
• Reîncercați 429 și 500 cu o scurtă pauză — așteptați, apoi încercați din nou. Nu reîncercați 400, 401, 403, 404 sau 409; acestea vor continua să eșueze până când modificați cererea.
• Citiți mesajul error. Acesta vă spune de obicei exact care câmp este greșit.

Paginare #

Punctele terminale de listare (cum ar fi GET /contacts, GET /campaigns și GET /tasks) returnează rezultatele în pagini, astfel încât un singur apel să nu fie nevoit să încarce întregul cont. Paginarea utilizează un cursor opac.

Doi parametri de interogare o controlează:

Fiecare pagină include un câmp next_cursor în răspuns:

• Dacă next_cursor este un șir de caractere, există mai multe rezultate — transmite-l ca cursor în următoarea ta solicitare.
• Dacă next_cursor este null, ai ajuns la ultima pagină. Oprește-te.

O singură pagină de contacte arată astfel:

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

Paginarea prin toate contactele #

Pentru a colecta o listă întreagă, începe fără cursor și continuă să apelezi până când next_cursor revine ca null.

cURL

Acest exemplu parcurge manual primele două pagini. Rulează primul apel, copiază next_cursor din răspunsul său în CURSOR, apoi rulează al doilea apel. Repetă până când next_cursor este 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

Aceeași buclă funcționează pentru orice endpoint paginat — doar schimbă calea și câmpul pe care îl citești din răspuns (campaigns, tasks și așa mai departe).

Pașii următori #

• Autentificare — cele patru modalități de a trimite cheia ta.
• Contacte — endpoint-urile complete pentru contacte utilizate în exemplele de mai sus.
• Chei API — verifică utilizarea curentă a limitei de rată pentru a evita 429.