APIエラーと安全な再試行

ステータスを確認する

APIエラーは原則として error.code と error.message を持つJSONで返ります。ZIP検証エラーでは、error.details.reason に具体的な理由が入ることがあります。

ステータス	主な意味	対応
201 Created	新しいロールの公開に成功	pin.url を利用する
200 OK	完了済みの作成を冪等再生、または取得・変更に成功	作成の再生時は Idempotency-Replayed: true を確認する
401 Unauthorized	APIキーがない、無効、または再生成で失効済み	ROR_API_KEY の設定を直してから再実行する
404 Not Found	ロールがない、またはAPIキーのアカウントが所有していない	IDと利用アカウントを確認する
409 Conflict	冪等リクエストが処理中、内容不一致、または削除状態が不正	error.code に応じて対応する
422 Unprocessable Entity	ZIP、項目、値、更新操作が不正	リクエストを修正してから新たに実行する
429 Too Many Requests	日次公開上限またはレート制限を超過	Retry-After の秒数だけ待つ
503 Service Unavailable	ストレージ障害、または公開反映待ち	作成リクエストでは同じ内容とIdempotency-Keyで再試行する

409を区別する

• request_in_progress: 同じIdempotency-Keyの処理がまだ進行中です。少し待ち、同じリクエストを同じキーで再送します。
• idempotency_mismatch: 同じキーが異なるZIP、元ファイル名、またはタイトルに使われています。元の論理操作なら内容を元に戻し、別の公開なら新しいキーを生成します。
• invalid_state: 削除済みなど、要求した状態変更を実行できません。再送では解消しません。

422は内容を修正する

archive_required、invalid_request、invalid_archive、invalid_update などは、そのまま再送しても成功しません。error.details.reason があれば、missing_index、サイズ超過、未対応ファイルなどの原因を修正してください。

503を同じキーで再試行する

• storage_unavailable: 公開前の保存処理などでストレージを利用できませんでした。
• publication_pending: コンテンツの保存は完了しましたが、共有URLへの最終反映が完了していません。details.pin_id と details.retryable: true が返ります。

publication_pending では、ZIP、元ファイル名、タイトル、Idempotency-Key を一切変えずに作成リクエストを再送してください。保存済みロールの公開ポインターを修復し、成功時は同じロールを 200 OK で返します。新しいキーへ変えると重複公開になるおそれがあります。

通信タイムアウトや作成時の storage_unavailable も、キーを付けていれば同じ作成リクエストとキーで再試行できます。

PATCHまたはDELETEで storage_unavailable が返った場合、データベースの変更だけが完了し、共有URLへの反映が途中のことがあります。GETの結果だけでは配信状態を判断できないため、時間をおいて同じ操作を再試行してください。再試行後はAPIの結果に加えて、共有URLが意図した状態になったことも確認します。

短い間隔で連打せず、待ち時間を段階的に延ばしてください。429 の場合は独自の待ち時間ではなく、必ず Retry-After を優先します。