Your AI Connector Docs

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

Status error_code Meaning What to do
200 — Success Read the response data.
201 — Resource created Save the returned ID (e.g. campaign_id, contactId).
400 400 Bad request A parameter is missing or invalid. Read the error message and fix the request.
401 401 Unauthorized Your API key is missing or invalid. Check the key and how you are sending it — see Authentication.
403 403 Forbidden Your plan does not include API access. See API Access or contact hi@youraiconnector.com.
404 404 Not found The resource (e.g. a contact, campaign, or task ID) does not exist on your account.
409 409 Conflict The resource already exists — for example, creating a contact whose phone number is already on your account.
429 429 Rate limited You have exceeded 300 requests per minute (or the wider 1,200/minute account ceiling). Back off and retry shortly.
500 500 Server error Something went wrong on our side. Retry after a short wait; email hi@youraiconnector.com if it persists.

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ä:

Parametri Kuvaus
limit Kuinka monta kohdetta palautetaan sivua kohden. Oletusarvot vaihtelevat päätepisteittäin (usein 50); maksimi on 100.
cursor Läpinäkymätön osoitin seuraavalle sivulle. Jätä pois ensimmäiseltä sivulta.

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

Huomautus: Kohdistin (cursor) on läpinäkymätön — älä yritä jäsentää, muodostaa tai muokata sitä. Välitä takaisin vain next_cursor-arvo, jonka sait aiemmasta vastauksesta.

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.