Erros e Paginação #

Esta página aborda dois aspetos que todas as integrações precisam de gerir: como é um pedido falhado e como paginar através de endpoints que devolvem listas.

O envelope de erro #

Quando um pedido falha, a resposta é sempre JSON com a mesma estrutura — um sinalizador success definido como false, uma mensagem error legível por humanos e um error_code numérico que corresponde ao estado HTTP:

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

Como success e error_code estão sempre presentes, pode ramificar com base neles sem inspecionar códigos de estado HTTP brutos, se preferir. Uma resposta bem-sucedida tem sempre success: true.

Códigos de estado #

Alguns exemplos de como isto se apresenta na prática:

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

Gerir erros corretamente #

• Verifique success (ou o código de estado) antes de ler os dados. Não assuma que o corpo da resposta contém o campo que espera.
• Tente novamente 429 e 500 com um curto período de espera — aguarde e tente de novo. Não tente novamente 400, 401, 403, 404 ou 409; estes continuarão a falhar até que altere o pedido.
• Leia a mensagem error. Geralmente, indica exatamente qual é o campo incorreto.

Paginação #

Os endpoints de lista (como GET /contacts, GET /campaigns e GET /tasks) devolvem resultados em páginas para que uma única chamada nunca tenha de carregar toda a sua conta. A paginação utiliza um cursor opaco.

Dois parâmetros de consulta controlam-na:

Cada página inclui um campo next_cursor na resposta:

• Se next_cursor for uma string, existem mais resultados — passe-a como o cursor no seu próximo pedido.
• Se next_cursor for null, chegou à última página. Pare.

Uma única página de contactos tem o seguinte aspeto:

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

Paginação de todos os contactos #

Para recolher uma lista completa, comece sem cursor e continue a chamar até que next_cursor devolva null.

cURL

Este exemplo percorre manualmente as duas primeiras páginas. Execute a primeira chamada, copie o next_cursor da sua resposta para CURSOR e, em seguida, execute a segunda chamada. Repita até que next_cursor seja 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

O mesmo ciclo funciona para qualquer endpoint paginado — basta alterar o caminho e o campo que lê da resposta (campaigns, tasks, e assim sucessivamente).

Próximos passos #

• Autenticação — as quatro formas de enviar a sua chave.
• Contactos — os endpoints de contacto completos utilizados nos exemplos acima.
• Chaves de API — verifique a sua utilização de limite de taxa em tempo real para evitar 429s.