メインコンテンツまでスキップ

エラーハンドリング

API は標準の HTTP ステータスコードを使用し、RFC 7807 Problem Details 形式でエラーを返します。

エラーレスポンスのフォーマット​

{
  "type": "https://feed.storyhub.studio/probs/auth",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key.",
  "instance": "/v1/feed"
}
フィールド説明
typeエラータイプを一意に識別する安定した URI
titleエラータイプの短い概要（人間向け）
statusHTTP ステータスコード
detailエラーの詳細な説明
instanceエラーが発生したリクエストパス

エラーの種類による分岐は type で判定してください。title は type ごとに固定された文言で、表示用途のみを想定しています。発生ごとに変わる情報は detail に含まれます。

ステータスコード​

コード意味対応方法
200成功—
202受理（非同期処理）イベントおよびプッシュジョブはキューに登録されます
400不正なリクエストリクエストパラメーターを確認してください
401認証エラーAPI Key を確認してください
402使用量上限超過クレジット残高を確認するか、上限を引き上げてください
403アクセス拒否API Key にこのリソースへの権限がありません
404リソースが見つかりませんリクエストされたリソースが存在しません
413ペイロード上限超過エンドポイント別のリクエストボディサイズおよび配列件数上限を確認してください（例: /v1/push-candidates の user_ids は最大 100,000 件）
429レート制限超過待機してリトライしてください（レート制限 を参照）
500サーバー内部エラーBackoff 付きでリトライしてください。継続する場合はサポートにお問い合わせください
503サービス一時停止一時的な障害です。Retry-After ヘッダーに従い、Backoff 付きでリトライしてください

413 レスポンス例​

{
  "type": "https://feed.storyhub.studio/probs/payload-too-large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "Request body exceeded the maximum allowed size of 2097152 bytes for this endpoint.",
  "instance": "/v1/events"
}

ボディサイズ上限は HTTP プロトコル層で適用されるため、chunked transfer encoding を用いても回避できません。

エラータイプ​

API が返す type と、それぞれに対応する title は次のとおりです。

typetitleステータス発生する場面
https://feed.storyhub.studio/probs/validationValidation Error400リクエストのパラメーターやボディが制約を満たしていない
https://feed.storyhub.studio/probs/authUnauthorized401API Key が未指定、または不正・失効している
https://feed.storyhub.studio/probs/usage-limit-exceededUsage Limit Exceeded402設定した使用量上限に達した状態でクレジット消費エンドポイントを呼び出した
https://feed.storyhub.studio/probs/forbiddenForbidden403対象リソースへの権限がない（例. content_id が直近このテナントに配信されていない）
https://feed.storyhub.studio/probs/tenant-statusTenant Suspended403アカウントが停止されている
https://feed.storyhub.studio/probs/not-foundResource Not Found404指定したリソースが存在しない、またはテナントに設定されていない
https://feed.storyhub.studio/probs/payload-too-largePayload Too Large413リクエストボディがエンドポイントのサイズ上限を超えた
https://feed.storyhub.studio/probs/rate-limitRate Limit Exceeded429レート制限を超過した
https://feed.storyhub.studio/probs/push-job-limitPush Job Limit Exceeded429同時実行中のプッシュ候補生成ジョブが上限に達している
https://feed.storyhub.studio/probs/internal-errorInternal Server Error500サーバー内部で予期しないエラーが発生した
https://feed.storyhub.studio/probs/service-unavailableService Unavailable503一時的な障害によりリクエストを処理できなかった
https://feed.storyhub.studio/probs/tenant-not-configuredTenant Not Configured503テナントのクレジット設定を参照できなかった

probs/... の URI はエラータイプを識別するための不変の識別子です。ブラウザーで開くとこのページにリダイレクトされますが、これは説明を読むための便宜であり、実装から取得する前提のエンドポイントではありません。エラーの判定は URI の文字列一致で行ってください。

リトライ戦略​

一時的なエラー（429、500、503）には、Exponential Backoff を使用してください（503 は Retry-After ヘッダーが付与される場合、その値を優先してください）：

wait_time = min(base_delay * 2^attempt, max_delay)
パラメーター推奨値
基本遅延1 秒
最大遅延30 秒
最大リトライ回数3 回

400、401、402、403、404 エラーはリトライ しないでください — これらはリクエストの修正が必要です。