エラーとページネーション #

このページでは、すべての統合で処理が必要となる2つの事項、つまり失敗したリクエストがどのようなものか、およびリストを返すエンドポイントのページネーション方法について説明します。

エラーエンベロープ #

リクエストが失敗した場合、レスポンスは常に同じ形式のJSONとなります。つまり、successフラグがfalseに設定され、人間が読めるerrorメッセージが含まれ、HTTPステータスと一致する数値のerror_codeが含まれます。

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

successとerror_codeは常に存在するため、必要に応じて生のHTTPステータスコードを検査することなく、それらに基づいて分岐処理を行うことができます。成功したレスポンスには常にsuccess: trueが含まれます。

ステータスコード #

これらが実際にどのように表示されるかの例をいくつか示します。

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

エラーの適切な処理 #

• データを読み取る前にsuccess（またはステータスコード）を確認してください。 レスポンスボディに期待するフィールドが含まれていると想定しないでください。
• 429と500は短いバックオフ（待機時間）を置いて再試行してください。 つまり、少し待ってから再度試してください。400、401、403、404、または409の場合は再試行しないでください。これらはリクエストを変更しない限り失敗し続けます。
• errorメッセージを読み取ってください。 通常、どのフィールドが間違っているかが正確に示されます。

ページネーション #

リストエンドポイント（GET /contacts、GET /campaigns、GET /tasksなど）は結果をページ単位で返すため、1回の呼び出しでアカウント全体を読み込む必要はありません。ページネーションには不透明なカーソルを使用します。

これを制御するクエリパラメータは2つあります。

各ページには、レスポンス内にnext_cursorフィールドが含まれています。

• next_cursor が文字列の場合、さらに結果が存在します。次のリクエストでそれを cursor として渡してください。
• next_cursor が null の場合、最後のページに到達しています。終了してください。

連絡先の1ページ分は以下のようになります：

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

すべての連絡先をページングする #

リスト全体を取得するには、カーソルなしで開始し、next_cursor が null になるまで呼び出しを続けてください。

cURL

この例では、最初の2ページを手動で辿ります。最初の呼び出しを実行し、そのレスポンスから next_cursor をコピーして CURSOR に設定し、2回目の呼び出しを実行します。next_cursor が 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

同じループがすべてのページネーション対応エンドポイントで機能します。パスとレスポンスから読み取るフィールド（campaigns、tasks など）を変更するだけです。

次のステップ #

• 認証 — キーを送信する4つの方法。
• 連絡先 — 上記の例で使用されている完全な連絡先エンドポイント。
• APIキー — 429 を回避するために、現在のレート制限の使用状況を確認してください。