エラーと制限

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

{ "message": "An API key is required." }

ステータス別の確認

APIキーの検証はワークスペースの存在確認より先です。キーがないリクエストは、ワークスペースが存在しなくても401になります。有効なキーで存在しないワークスペースへアクセスすると404です。APIキーの対象外のAPIへアクセスした場合も404です。

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

言語を指定した取得では、未設定の言語コード、多言語でないAPIへのサブ言語指定、不正なlang_fallback、未知のincludeキーは400です。言語コードとAPIの多言語設定を確認してください。指定した言語版が未作成・非公開なら、単一・オブジェクト取得は404、一覧はその原稿を除いた200です。公開中のメイン言語で代わりに返したい場合はlang_fallback=trueを指定します。

レート制限

配信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は送らないでください。

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