Errores y paginación #

Esta página cubre dos aspectos que toda integración debe gestionar: cómo es una solicitud fallida y cómo paginar a través de endpoints que devuelven listas.

El sobre de error #

Cuando una solicitud falla, la respuesta es siempre un JSON con la misma estructura: un indicador success establecido en false, un mensaje error legible por humanos y un error_code numérico que coincide con el estado HTTP:

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

Debido a que success y error_code siempre están presentes, puede ramificar su lógica basándose en ellos sin necesidad de inspeccionar los códigos de estado HTTP sin procesar si lo prefiere. Una respuesta exitosa siempre tiene success: true.

Códigos de estado #

Algunos ejemplos de cómo se ven en la práctica:

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

Cómo gestionar bien los errores #

• Compruebe success (o el código de estado) antes de leer los datos. No asuma que el cuerpo de una respuesta contiene el campo que espera.
• Reintente 429 y 500 con un breve periodo de espera (back-off): espere y vuelva a intentarlo. No reintente 400, 401, 403, 404 o 409; seguirán fallando hasta que cambie la solicitud.
• Lea el mensaje error. Por lo general, le indica exactamente qué campo es incorrecto.

Paginación #

Los endpoints de lista (como GET /contacts, GET /campaigns y GET /tasks) devuelven resultados en páginas para que una sola llamada nunca tenga que cargar toda su cuenta. La paginación utiliza un cursor opaco.

Dos parámetros de consulta la controlan:

Cada página incluye un campo next_cursor en la respuesta:

• Si next_cursor es una cadena, hay más resultados: pásala como el cursor en tu siguiente solicitud.
• Si next_cursor es null, has llegado a la última página. Detente.

Una sola página de contactos se ve así:

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

Paginación de todos los contactos #

Para recopilar una lista completa, comienza sin cursor y sigue realizando llamadas hasta que next_cursor devuelva null.

cURL

Este ejemplo recorre las dos primeras páginas manualmente. Ejecuta la primera llamada, copia el next_cursor de su respuesta en CURSOR y luego ejecuta la segunda llamada. Repite hasta que next_cursor sea 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

El mismo bucle funciona para cualquier endpoint paginado; solo cambia la ruta y el campo que lees de la respuesta (campaigns, tasks, etc.).

Próximos pasos #

• Autenticación: las cuatro formas de enviar tu clave.
• Contactos: los endpoints completos de contactos utilizados en los ejemplos anteriores.
• Claves de API: consulta tu uso actual del límite de tasa para evitar 429s.