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

エラーハンドリング

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

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

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key.",
  "instance": "/v1/feed"
}
フィールド説明
typeエラータイプの URI（現在は about:blank）
title人間が読める短い概要
statusHTTP ステータスコード
detailエラーの詳細な説明
instanceエラーが発生したリクエストパス

ステータスコード​

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

413 レスポンス例​

{
  "type": "https://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 を用いても回避できません。

リトライ戦略​

一時的なエラー（429、500）には、Exponential Backoff を使用してください：

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

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