確認日2026-11-10 · API版2026-11-09 · Markdownを読む
エラー、リトライ、復旧
API エラーは { "error": { "code": "…", "message": "…", "requestId": "…" } }
を使用し、オプションでフィールドエラー、宛先エラー、リトライのヒント、アクションのハンドオフを伴います。
サポートのために requestId を保持してください。診断情報を収集する際は、資格情報、署名付きアップロード URL、
機密性の高いリクエスト内容をログに記録しないでください。
| レスポンス | 復旧方法 |
|---|---|
401 unauthenticated | 欠落、不正、または失効したプロダクトキーを確認 |
403 forbidden_scope / account_not_allowed | キーのスコープと宛先へのアクセスを見直し |
402 account_limit、seat_limit、storage_limit | ワークスペースの権限とリソース使用を見直し |
402 subscription_inactive / trial_expired | 請求状態を解消。下書きと待機中の作業を保持 |
409 revision_conflict | 現在のバージョンを読み取り、変更を確認して意図的に再適用 |
409 idempotency_conflict | キーが異なるボディで再利用された。元の操作と突き合わせて調整 |
409 consent_required | 権限のある人に、提供されたレビューのハンドオフを完了してもらう |
409 too_late_to_cancel | 実際の配信ステータスを確認。キャンセルの成功を主張しない |
media_expired / media_deleting | 元のファイルを再アップロードし、下書きを更新 |
422 validation_failed | 構造化されたフィールドまたは宛先ごとの問題を修正 |
429 rate_limited | Retry-After に従う。同時実行を減らしバックオフを使用 |
submission_unknown | 別の提出を試みる前に、既存の外部の結果と突き合わせて調整 |
安全なミューテーションのリトライ
最初のミューテーションの前に冪等性キーを生成し、その正確なリクエストを保存してください。
レスポンスが失われた場合、操作はすでに成功している可能性があります。同じキーで
同一のリクエストを再生してください。ネットワークがタイムアウトしたという理由だけで新しいキーを
生成してはなりません。MCP のミューテーションツールは、
transport_outcome_unknown の失敗を含め、キーをエコーします。アダプタはミューテーションを自動リトライしません。
ワークスペースの技術的な速度制限は投稿クレジットではありません。現在の
プランとレート情報は /usage で確認してください。バックオフは一時的なエラーに対してのみ
状況に応じて行ってください。認可、検証、人間の同意のエラーは、
原因を変えずに再試行しても効果がありません。
部分成功と観察
受け付けられた公開/予約のバッチは、独立した配信の集合です。成功した レシートとネイティブリンクを保持してください。失敗した宛先は、バッチ全体を 再作成するのではなく、その宛先自身のリトライエンドポイントで復旧します。署名付きの ウェブフック を推奨します。ポーリングする場合は、遅延を増やしながらの上限付きの試行回数とし、未解決の作業は人間に表面化してください。