エラー

Management API、Content Delivery API、Customer APIは、すべて同じ形式でエラーを返します。各コードはすべてのAPIで常に同じHTTPステータスに対応しているため、1つのエラーハンドラーですべてのAPIに対応可能です。

{
  "error": {
    "code": "SLUG_TAKEN",
    "message": "Another post already uses this slug.",
    "details": { "slug": "how-we-feed-our-starter" }
  }
}

成功時のレスポンスには error は含まれず、APIが成功を ok フラグでラップすることもありません。

コード別のHTTPステータス

すべてのコードは1つのステータスに対応しています。後から追加されたコードも同じルールに従うため、未確認のコードであってもステータスに基づいて処理できます。

APIリファレンスの各操作には、返される可能性のあるコードとその操作における意味が記載されています。OpenAPIドキュメントにも、x-kanorio-errors として同じリストが記載されています。

バリデーションエラー

VALIDATION は、details.issues 内のすべての失敗したフィールドをリスト化します。path はドットを使用してネストを表現します。

{
  "error": {
    "code": "VALIDATION",
    "message": "Input does not match the capability schema.",
    "details": {
      "issues": [
        { "path": "title", "message": "Required", "code": "invalid_type" }
      ]
    }
  }
}

Content Delivery APIでのフォーム送信において無効な回答があった場合も同様の方法で報告され、path には質問IDが使用されます。

リトライ

• 429、502、503 はバックオフを使用してリトライしてください。レスポンスに Retry-After ヘッダーまたは details.retryAfter が含まれている場合は、指定された秒数以上待機してください。
• 他の 4xx レスポンスは、修正せずにリトライしないでください。まずリクエストを修正してください。
• 書き込み時の 409 CONFLICT は、読み取り後に誰かがリソースを変更したことを意味します。再度読み取りを行い、マージしてから新しいタイムスタンプで書き込みリクエストを送信してください。
• 作成リクエストは、冪等性キーを使用して安全にリトライできるようにしてください。

権限エラー

403 レスポンスの details には不足している情報が説明されています。例えば、トークンに不足している requiredScope や、サービスアカウントがアカウントレベルの操作を呼び出した際の reason: "principal_not_allowed" などが含まれます。リトライするのではなく、ユーザーに何を修正すべきかを表示してください。

リクエストID

Content Delivery APIおよびCustomer APIのレスポンスには X-Request-Id ヘッダーが含まれています。特定の操作についてサポートに問い合わせる際は、このIDを提示してください。

エラーコード

以下の表は、OpenAPIドキュメントから生成された、各APIが現在返す可能性のあるすべてのコードの一覧です。

Management API codes

Content Delivery API codes

Customer API codes