エラーレスポンス

API の呼び出しが失敗し、詳細なエラー内容が提供可能な場合には、HTTP Response Body に含まれる以下の JSON Error Object によりエラー内容が示されます。
エラー原因の概要はエラーコードとして code に示され、詳細情報は description に記載されます。

{  "code": "ERROR_CODE",  "description": "error description"}

エラーコード {#error-code}

一般的に発生するエラーの code とその説明は以下のとおりです。

HTTP Status Codecode説明
400BAD_REQUESTクライアントからの誤った形式または内容の要求による一般的なエラー
400INVALID_PARAMETERクライアントからのリクエストに含まれるパラメータの形式または内容に問題がある
400INVALID_{RESOURCE}クライアントから要求されたリソースの内容に問題がある
400MISSING_PARAMETER呼び出しに必要なパラメータが不足している
400LIMIT_EXCEEDEDパラメータまたはリソースの制限を超えた
400OUT_OF_RANGEパラメータまたはリソースの制限の範囲外
401UNAUTHORIZED必要な認証情報が欠落しているか誤っている
一般的な認証エラーは RFC 6749 を確認してください
403FORBIDDENサーバーはリクエストの内容を理解したが、拒否した
アクセス対象のリソースへのアクセス権がない場合や、アプリがアクセス対象のリソースへの OAuth スコープを保持していない場合も含みます
403ACCESS_DENIEDクライアントが要求したリソースへのアクセスが制限されている
403LIMIT_EXCEEDEDクライアントが要求したリソースの制限を超えた
403OUT_OF_RANGEクライアントが要求したリソースの制限の範囲外
404NOT_FOUNDクライアントが要求したリソースが存在しない
404{RESOURCE}_NOT_EXISTクライアントが要求した特定のリソースが存在しない
409CONFLICTクライアントが要求したリソースで競合が発生した
409ALREADY_EXISTクライアントが作成しようとしたリソースが既に存在する
409{RESOURCE}_ALREADY_EXISTクライアントが作成しようとした特定のリソースが既に存在する
500INTERNAL_SERVER_ERRORサーバーの内部エラー
503SERVICE_UNAVAILABLE一時的なサーバーエラー

エラーの発生原因の確認 {#error-cause}

API 呼び出しのエラーの原因に応じて、レスポンスの WWW-Authenticate ヘッダーでもエラーの原因が示されます。RFC 6750 に従った内容が返されます。

注意

  • レスポンスヘッダーのフィールド名は大文字小文字を区別せずに扱ってください。表記が予告なく変更される可能性があります。
  • 参考: https://www.rfc-editor.org/rfc/rfc9110#section-5.1

WWW-Authenticate Header {#www-authenticate-header}

WWW-Authenticate ヘッダーの構造は以下のとおりです。

WWW-Authenticate {auth-scheme} {auth-param}, {auth-param}...
  • auth-scheme: 'Bearer' で固定
  • auth-param
    • scope: Access Token が、API の呼び出しに必要な Scope を持っていない場合に含まれる。リクエストした API の呼び出しに必要な Scope を含む。
    • error: エラーコード。エラーの原因により異なる値を含む。
HTTP Status CodeWWW-Authenticate説明
400WWW-Authenticate: Bearer error="invalid_request"リクエストのパラメータ形式が間違っている
401WWW-Authenticate: Bearer error="invalid_token"Access Token が誤っている
403WWW-Authenticate: Bearer error="insufficient_scope", scope="{scope list}"Access Token が、API の呼び出しに必要な Scope を持っていない

参考
WWW-Authenticate は、エラー レスポンスに対して必ず含まれるわけではありません。 HTTP Status Code が 400、401、または 403 の場合のうち、特定のケースにおいてのみ含まれるレスポンス情報です。