Notiondesk APIエラー、レート制限、および再試行を処理する

Notiondesk API は、すべてのエラーに対して同じ JSON エンベロープと機械可読な code ヘッダーで応答し、各キーの読み取り回数を 1 分あたり 120 回、書き込み回数を 20 回に制限し、Idempotency-Key ヘッダーを使用して変更を安全に再試行できるようにします。この記事では、すべての Notiondesk API エラー コードの一覧、レート制限とそのヘッダーの説明、および同じ操作を二度行わない再試行方法を示します。

Notiondesk API エラーエンベロープ

すべてのエラーは同じ形状に対応し、すべてのフィールドは常に存在します。

{
  "object": "error",
  "code": "validation_error",
  "message": "The request parameters are invalid.",
  "request_id": "0f2c1e94-7a1b-4c2d-9e3f-5a6b7c8d9e0f",
  "errors": [
    {"field": "page_size", "message": "This value should be between 1 and 100."}
  ]
}

field が値に名前を付ける方法

• 最上位フィールドは、その名前である page_size です。

• リスト内のフィールドは、リスト名、括弧内のエントリ名、フィールド名の順になります。例: items[fr].page_title。

• 括弧内には、各エントリに固有の識別子がある場合、送信されたエントリの識別子（locale は items に、category_id は changelog_categories に格納）が格納されます。それ以外の場合は、エントリのゼロベースの位置（items[0].locale）が格納されます。

• リクエスト全体に問題があり、"field": null となっています。

Notiondesk APIエラーコード

ワークスペース外のヘルプセンターやリソースへのリクエストは404 not_foundという応答を返すため、APIはそれが存在するかどうかを公開しません。

Notiondesk APIレート制限

各APIキーと各OAuthグラントには、1分間のスライディングウィンドウでカウントされる2つのリクエストバジェットがあります。

分析レポートも、ワークスペース内のすべてのキーとOAuthアプリで共有される、ヘルプセンターごとに1分あたり30件のリクエストという予算にカウントされます。

回答には3つのヘッダーが含まれます。

予算を超えるリクエストに対しては、429 rate_limited という応答が返されます。次のリクエストを送信する前に、Retry-After で指定された秒数だけ待機してください。

注：レート制限はワークスペースごとではなく、キーごと、またはOAuth認証ごとにカウントされます。共有分析予算を除き、別々のキーを使用する2つの統合は互いの速度を低下させることはありません。

Idempotency-Key を使用して安全に再試行してください。

ネットワークタイムアウトが発生すると、変更が正しく反映されたかどうかが不明確になります。Idempotency-Key ヘッダーを使用すると、何も変更せずに同じリクエストを再度送信できます。

何らかの変更を加えるすべてのルートは、その変更を受け入れます。ページリダイレクトの変更、設定やブランディングの更新、統合の変更、同期トリガーなどです。最初の試行では、UUIDなどの1～255文字の一意の値を送信し、再試行のたびに同じ値を送信します。

再試行時に何が起こるか：

curl -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0d6b1e-create-getting-started" \
  -d '{"type": "article", "source_path": "/legacy/getting-started", "target_id": "1761580412", "locale": "en"}'

応答が成功した場合、初回はX-Idempotent-Replay: false、再送信時はtrueが渡されます。Notiondeskはキーを少なくとも24時間保持します。キーは、それを送信したAPIキーまたはOAuthグラントに属し、OAuthグラントはトークンの更新後もキーを保持します。

ヘッダーがない場合、リクエストは一度実行され、再試行は再度実行されます。

効果的な再試行戦略

1. 論理的な変更ごとに Idempotency-Key を 1 つ生成し、その変更を再試行するたびにそれを再利用します。

2. 429 rate_limited の場合、Retry-After 秒間待機してから再試行します。

3. 409 request_in_progress では、数秒待ってから同じキーで再試行してください。409 conflict_error では、ヘルプセンターの同期が既に実行中です。数分待ってから再度トリガーするか、この実行をスキップしてください。

4. 500以上、またはネットワークエラーが発生した場合は、1秒、2秒、4秒、8秒などの指数バックオフで再試行します。

5. 400、401、403、404、または422を変更せずに再試行しないでください。まずリクエストを修正してください。

JavaScriptでは、何らかの変更を加えるルートの場合、conflict_errorで停止し、その後の判断はコードに委ねられます。

よくある質問

import { randomUUID } from "node:crypto";

const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function notiondeskRequest(method, path, body, attempts = 5) {
  const idempotencyKey = randomUUID();

  for (let attempt = 0; attempt < attempts; attempt++) {
    let response;
    try {
      response = await fetch(`https://api.notiondesk.so${path}`, {
        method,
        headers: {
          Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
          "nd-version": "2026-10-16",
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        body: body ? JSON.stringify(body) : undefined,
      });
    } catch {
      await sleep(2 ** attempt);
      continue;
    }

    if (response.ok) {
      return response.status === 204 ? null : response.json();
    }

    const error = await response.json().catch(() => ({}));
    const retryable = response.status === 429 || response.status >= 500 || error.code === "request_in_progress";
    if (!retryable) {
      throw new Error(`${response.status} ${error.code}: ${error.message}`);
    }

    const retryAfter = Number(response.headers.get("Retry-After"));
    await sleep(retryAfter > 0 ? retryAfter : 2 ** attempt);
  }

  throw new Error(`Notiondesk request failed after ${attempts} attempts`);
}

次は？

• ページネーションとバージョン Notiondesk API リクエスト

• APIキーを使用してNotiondesk APIで認証します。

• Notiondesk REST API を使い始めましょう