エラーと制限

配信APIのエラーは、HTTPステータスとJSONのmessageで返ります。メッセージは原因を調べるために使い、アプリの分岐はステータスを基準にしてください。

{ "message": "APIキーが必要です。" }

ステータス別の確認

存在する記事でも、非公開なら通常の単一取得は404です。一覧の検索結果が0件の場合はエラーではなく、200と空配列を返します。

レート制限

配信APIの上限はAPIキーごとに1分300リクエストです。リクエストを並列で大量に送ると、記事数が少なくても上限へ達する場合があります。

• 同じコンテンツの重複取得をまとめる。
• 用途に合ったキャッシュを使う。
• ビルドや一括取得では同時実行数を抑える。
• 再試行する場合は回数に上限を設け、待ち時間を増やす。

SDKには標準の自動リトライはありません。getAll()も内部では複数のリクエストを送ります。制限回避のためにキーを増やす運用は行わないでください。

SDKでエラーを扱う

APIからのエラー応答はGenkoApiErrorになります。ネットワーク障害など、HTTPレスポンスを受け取れなかった失敗は別の例外になる場合があります。

import { GenkoApiError } from "@genko-me/sdk";
import { genko } from "@/lib/client";

try {
  const result = await genko.apis.blog.list();
  console.log(result.totalCount);
} catch (error) {
  if (error instanceof GenkoApiError) {
    console.error("genko API error", error.status, error.message);
  }
  throw error;
}

詳細ページで404だけを欠損として扱いたい場合はgetOrNull()を使います。認証エラーやサーバーエラーはnullにならず、例外として伝わります。

調査に必要な情報

解決しない場合は、発生日時、対象のワークスペース・エンドポイント、HTTPステータス、メッセージ、再現手順をまとめて[email protected]へ連絡してください。APIキー、パスワード、プレビューキーを含むURLは送らないでください。

画面操作や設定の問題はトラブルシューティングを参照してください。