APIのエラー形式とエラーコード

APIのエラーレスポンスはすべて同じ形式です。コードでは、messageのテキストではなく、errorフィールドのエラーコードを頼りにしてください。コードは変わりませんが、テキストは変わることがあり、アカウント言語に翻訳されます。

#エラーレスポンスの構造

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

機械可読なコードです（例：not_found）。ほとんどのエラーではX-Error-Codeヘッダーにも入っていますが、本文のフィールドを頼りにしてください。

message

人が読める説明で、アカウント言語で書かれています。APIキーの場合はワークスペースのオーナーの言語、接続したアプリの場合は接続した人の言語です。トークンのチェックによる401など、有効なトークンがない場合はAccept-Languageに従い、それもなければ英語です。言語はContent-Languageヘッダーに示されます。

details

追加の情報があるときだけ含まれます。入力の検証による422では、問題ごとにfield、reason、messageを含むリストです。業務ロジックによる422やその他のすべてのエラーでは、reason、retry_after_sec、問題のリストなどを含むオブジェクトです。サイズ超過の場合はfield、reason、limitを含み、413 request_too_largeではmax_bytesとmax_kbを含みます。そのため、detailsがリストかどうかを確認してください。

request_id

リクエストのIDです。X-Request-Idヘッダーにも入っています。サポートに問い合わせるときは添えてください。

例外：429 rate_limitedのレスポンスにはdetailsの代わりにretry_after_secフィールドがあります。429と403 insufficient_scopeでは、本文にrequest_idがありません。トークンのチェックによる401とスキーマチェックによる422にはX-Error-Codeヘッダーがなく、スキーマチェックでは最上位のmessageだけが翻訳され、details内のテキストは英語のままです。X-Request-Idヘッダーは常に設定されます。

#主なコード

#入力エラーの読み方

422 validation_failedでは、detailsにすべての問題が個別に一覧表示されます。fieldはフィールドのパス（ネストしたオブジェクトはスラッシュ区切り、例：theme_config/button_style）、reasonは違反したルール（required、minLength、maxLength、enum、additionalPropertiesなど）です。additionalPropertiesの場合、messageにどのフィールドが不明かが示されます。多くの場合、フィールド名の入力ミスです。

#コードでの推奨される対応

• 400、413、422：再試行せず、リクエストを修正してください
• 401 invalid_token：新しいトークンを一度取得して再試行してください
• 403：再試行せず、スコープ、プラン、誰がこの操作をできるかを確認してください
• 404：IDを確認してください。削除後であれば正常です
• 409：状態を読み込み直し、その操作がまだ必要か判断してください
• 429：Retry-Afterの時間だけ待ってから再試行してください。レート制限をご覧ください
• 500と503：間隔を広げながら数回再試行してください