Virheet ja sivutus #

Tämä sivu käsittelee kahta asiaa, jotka jokaisen integraation on hallittava: miltä epäonnistunut pyyntö näyttää ja miten sivutetaan päätepisteitä, jotka palauttavat listoja.

Virhekuori #

Kun pyyntö epäonnistuu, vastaus on aina JSON-muodossa, jolla on sama rakenne — success-lippu asetettuna arvoon false, ihmisluettava error-viesti ja numeerinen error_code, joka vastaa HTTP-tilaa:

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

Koska success ja error_code ovat aina läsnä, voit tehdä niihin perustuvia valintoja ilman, että sinun tarvitsee tarkistaa raakoja HTTP-tilakoodeja, jos haluat. Onnistuneessa vastauksessa on aina success: true.

Tilakoodit #

Muutama esimerkki siitä, miltä nämä näyttävät käytännössä:

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

Virheiden hyvä käsittely #

• Tarkista success (tai tilakoodi) ennen tietojen lukemista. Älä oleta, että vastausrunko sisältää odottamasi kentän.
• Yritä uudelleen 429 ja 500 lyhyellä viiveellä — odota ja yritä sitten uudelleen. Älä yritä uudelleen 400, 401, 403, 404 tai 409; ne epäonnistuvat jatkossakin, kunnes muutat pyyntöä.
• Lue error-viesti. Se kertoo yleensä tarkalleen, mikä kenttä on virheellinen.

Sivutus #

Listapäätepisteet (kuten GET /contacts, GET /campaigns ja GET /tasks) palauttavat tulokset sivuina, jotta yksittäisen kutsun ei tarvitse ladata koko tiliäsi. Sivutus käyttää läpinäkymätöntä osoitinta (cursor).

Kaksi kyselyparametria ohjaavat sitä:

Jokainen sivu sisältää next_cursor-kentän vastauksessa:

• Jos next_cursor on merkkijono, tuloksia on lisää – välitä se cursor-parametrina seuraavassa pyynnössäsi.
• Jos next_cursor on null, olet saavuttanut viimeisen sivun. Lopeta.

Yksittäinen yhteystietosivu näyttää tältä:

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

Kaikkien yhteystietojen selaaminen #

Voit hakea koko luettelon aloittamalla ilman osoitinta ja jatkamalla kutsumista, kunnes next_cursor palauttaa arvon null.

cURL

Tämä esimerkki käy läpi kaksi ensimmäistä sivua manuaalisesti. Suorita ensimmäinen kutsu, kopioi vastauksesta saatu next_cursor kohtaan CURSOR ja suorita sitten toinen kutsu. Toista, kunnes next_cursor on 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

Sama silmukka toimii kaikissa sivutetuissa päätepisteissä – muuta vain polku ja kenttä, jota luet vastauksesta (campaigns, tasks jne.).

Seuraavat vaiheet #

• Todennus – neljä tapaa lähettää avaimesi.
• Yhteystiedot – yllä olevissa esimerkeissä käytetyt täydelliset yhteystietojen päätepisteet.
• API-avaimet – tarkista reaaliaikainen nopeusrajoitusten käyttösi välttääksesi 429-virheet.