Erreurs et pagination #

Cette page couvre deux aspects que toute intégration doit gérer : à quoi ressemble une requête ayant échoué et comment paginer les points de terminaison qui renvoient des listes.

L’enveloppe d’erreur #

Lorsqu’une requête échoue, la réponse est toujours au format JSON avec la même structure : un indicateur success défini sur false, un message error lisible par l’homme et un error_code numérique qui correspond au code d’état HTTP :

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

Comme success et error_code sont toujours présents, vous pouvez baser votre logique dessus sans avoir à inspecter les codes d’état HTTP bruts si vous préférez. Une réponse réussie contient toujours success: true.

Codes d’état #

Quelques exemples de ce à quoi cela ressemble en pratique :

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

Bien gérer les erreurs #

• Vérifiez success (ou le code d’état) avant de lire les données. Ne supposez pas qu’un corps de réponse contient le champ que vous attendez.
• Réessayez 429 et 500 avec un court délai d’attente — attendez, puis réessayez. Ne réessayez pas 400, 401, 403, 404 ou 409 ; ces requêtes continueront d’échouer tant que vous ne modifierez pas la requête.
• Lisez le message error. Il vous indique généralement exactement quel champ est incorrect.

Pagination #

Les points de terminaison de liste (tels que GET /contacts, GET /campaigns et GET /tasks) renvoient les résultats par pages afin qu’un seul appel n’ait jamais à charger l’intégralité de votre compte. La pagination utilise un curseur opaque.

Deux paramètres de requête la contrôlent :

Chaque page inclut un champ next_cursor dans la réponse :

• Si next_cursor est une chaîne de caractères, il y a d’autres résultats — transmettez-la en tant que cursor lors de votre prochaine requête.
• Si next_cursor est null, vous avez atteint la dernière page. Arrêtez.

Une page unique de contacts ressemble à ceci :

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

Pagination de tous les contacts #

Pour récupérer une liste complète, commencez sans curseur et continuez à effectuer des appels jusqu’à ce que next_cursor soit null.

cURL

Cet exemple parcourt manuellement les deux premières pages. Exécutez le premier appel, copiez le next_cursor de sa réponse dans CURSOR, puis exécutez le second appel. Répétez l’opération jusqu’à ce que next_cursor soit 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

La même boucle fonctionne pour n’importe quel point de terminaison paginé — changez simplement le chemin et le champ que vous lisez dans la réponse (campaigns, tasks, etc.).

Étapes suivantes #

• Authentification — les quatre méthodes pour envoyer votre clé.
• Contacts — les points de terminaison complets des contacts utilisés dans les exemples ci-dessus.
• Clés API — vérifiez votre utilisation actuelle de la limite de débit pour éviter les 429.