ポイント エラーコード
ポイントのAPIで返るエラーの一覧と、ポイント固有のエラー項目 providerCode について説明します。
OpenAPIタイプ共通のエラー仕様(HTTPステータスコードの意味、エラーレスポンスの形式、title の全一覧)はエラー仕様を参照ください。
エラーレスポンスの形式
ポイントのAPIがエラーになった場合、RFC 9457に従ったエラー情報が返ります。
ポイントでは、共通項目に加えて providerCode が返ることがあります。
{
"title": "processing_failure",
"detail": "The point provider returned an error.",
"instance": "/point/use",
"providerCode": "E052000000"
}
| キー | 説明 | 例 |
|---|---|---|
| title | エラーの内容サマリー エラーコードとして取り扱えます 一覧は以下の表を参照ください | processing_failure |
| detail | エラーの詳細説明 エラーメッセージとして取り扱えます 全て英文です。 | The point provider returned an error. |
| instance | エラーが発生したエンドポイント | /point/use |
| providerCode | ポイント事業者が返却したエラーコード ポイント事業者起因のエラー時のみ設定されます | E052000000 |
providerCode について
providerCode は、ポイント事業者のAPIが返したコードを 変換せずそのまま 返す項目です。
- コードの体系と意味は ポイント事業者ごとに異なります(例:Pontaポイントの
E052000000、Vポイントの22-101) - ポイント事業者がコードを返さない場合は設定されません
- 当サービスが判定したエラー(パラメーター不正など)では設定されません
providerCode は当サービスでは意味を解釈しないため、加盟店様の処理分岐には title を使用してください。
providerCode は、お客様の画面に表示するメッセージの決定、お客様からの問い合わせ対応、ポイント事業者への調査依頼の際にご利用ください。
title ごとに返る可能性がある providerCode はtitle と providerCode の対応を参照ください。
providerCode ごとに定められていますPontaポイント・Vポイントでは、ポイント事業者起因のエラー時にお客様へ表示するメッセージがポイント事業者との取り決めで定められています。
事業者エラーメッセージの文言を表示してください。
コードの意味についてお問い合わせが必要な場合は、title・detail・providerCode・accessId をあわせてお問い合わせください。
ポイントのAPIで返るエラー
ポイントのAPIで返る title の一覧です。
| title名 | 説明 | 加盟店様の対応 | HTTP ステータス コード |
|---|---|---|---|
| missing_parameter | 必須パラメーターが設定されていません。 ポイント事業者ごとに必須の項目が異なります | detail の項目名を確認し、事業者別の仕様差異を参照して必須パラメーターを設定してください | 400 |
| invalid_parameter | リクエストパラメーターの書式・桁数が不正です。 ポイント事業者ごとに異なる形式・上限に反する場合も含みます | detail の項目名を確認して修正してください。ポイント事業者ごとの形式・上限は事業者別の仕様差異を参照ください | 400 |
| unsupported_operation | 指定したポイント事業者が対象の操作に対応していません。 ポイント付与の部分取消を指定した場合も含みます | 事業者別の仕様差異で対応APIを確認してください | 400 |
| approval_not_found | ポイント認可が存在しない、または解除されています。 指定した pointAccountReference が認可済みの内容と一致しない場合も含みます | memberId と pointAccountReference がポイント認可結果確認(/point/memberinquiry)APIで取得した値であることを確認してください。認可が存在しない場合はポイント認可開始( /point/start)APIから認可し直してください | 400 |
| approval_terminated | ポイント認可が無効、または有効期限切れです | 同上 | 400 |
| invalid_status | 対象の取引状態に対して処理できないリクエストです。 既に取消済み、取消できない状態、既に認可済みなどの場合に発生します | ポイント取引照会(/point/inquiry)APIで取引状態を確認してください | 400 |
| transaction_not_found | 対象の取引が存在しません | accessId / orderId を確認してください | 400 |
| transaction_already_exists | 対象の取引が既に存在します。orderId の重複も含みます | orderId を一意の値にしてください | 400 |
| transaction_expired | 処理期限を超過しています。 ポイント利用取消・利用ポイント変更の期限超過時に発生します | 元取引の処理可能期間を確認してください | 400 |
| transaction_count_exceeded | 同一取引に対する処理上限を超過しています。 利用ポイント変更は1取引につき1回まで です | 2回目以降の変更が必要な場合はポイント利用取消(/point/cancel)APIで全額取消のうえ、再度ポイント利用(/point/use)APIを実行してください | 400 |
| member_not_found | 対象の会員が存在しません | memberId を確認してください | 400 |
| invalid_contract | 対象ショップの契約状態が無効、またはショップの設定が不足しています | ポイントのご利用契約と設定状況をご確認ください | 400 |
| member_terminated | 対象の会員のポイント利用が停止されています | お客様にポイント利用が停止されている旨を案内してください。providerCode は対応表を参照ください | 400 |
| insufficient_balance | ポイント残高が不足しています。usePoint が salesAmount を超えた場合も同じエラーが返ります | お客様に残高不足を案内してください。事前にポイント残高照会(/point/balance)APIで利用可能ポイント数を確認することで回避できます。usePoint と salesAmount の関係は加盟店様側でご確認ください | 402 |
| operation_aborted_by_user | お客様の操作によりポイント認可が中止されました | お客様に中止を案内してください | 402 |
| processing_failure | ポイント事業者からエラーが返りました。 ポイント口座の利用停止、連携数上限の超過、付与ポイント数が付与率と整合しない場合などが含まれます | detail と providerCode を確認してください。お客様側の状態に起因する場合はお客様への案内が必要です。付与ポイント数については事業者別の仕様差異を参照ください | 402 |
| too_many_requests | 同時接続数の上限を超過しています。 ポイント事業者またはポイントGWの処理上限を一時的に超過した場合も含みます | 時間をおいて再実行してください | 429 |
| internal_server_error | 当サービスのサーバーで問題が発生しました | 時間をおいて再実行してください。継続する場合はお問い合わせください | 500 |
| bad_gateway | ポイント事業者やネットワークで問題が発生しました。 ポイント事業者のタイムアウトのほか、ポイント事業者が一時的に利用できない場合も含みます | 時間をおいて再実行してください。ポイント事業者が一時的に利用できない場合は、ポイント事業者へ処理が送信されていません。処理結果が不明な場合はポイント取引照会(/point/inquiry)APIで状態を確認してください | 502 |
| maintenance | ポイント事業者がメンテナンス中です | 時間をおいて再実行してください | 502 |
title と providerCode の対応
Pontaポイント・Vポイントの、ポイント事業者起因のエラーで title ごとに返る可能性がある providerCode の一覧です。
1つの title に複数のポイント事業者・複数のコードが対応します。処理分岐は title で行い、providerCode は問い合わせ対応やお客様へのメッセージ表示にご利用ください。
| title | Pontaポイント | Vポイント |
|---|---|---|
invalid_parameter | E041000000 | — |
approval_not_found | E030000000E031000000 | 22507022-202 |
approval_terminated | — | 404142 |
invalid_status | — | 22-101 |
transaction_not_found | — | 15 |
transaction_already_exists | E024000000E040000000 | 05 |
member_not_found | E021000000E032000000E033000000 | 101151 |
invalid_contract | E025000000 | 18 |
insufficient_balance | E052000000 | 17 |
member_terminated | E058000000E059000000N058000000-02N058000000-03 | 12131431 |
operation_aborted_by_user | E154000999 | — |
processing_failure | E023000000E068000000E090000000E099000000E161000999F501000000F590000000 | 414243444552539922-20022-201 |
too_many_requests | E900000000 | — |
bad_gateway | E001+6桁E002+6桁E003+6桁E004+6桁E005000000E006000000E007000000E008000000E009000000E010000000E067000000E069000000E090000000E511000000F502000000 | 041623309092 |
maintenance | — | 80 |
- 表の
titleはX-MP-Versionが2026-07の場合です。2023-05では、approval_not_found・approval_terminated・transaction_not_found・transaction_already_exists・member_not_foundはinvalid_request、member_terminatedはprocessing_failureで返ります —の欄は、そのポイント事業者では該当するproviderCodeがないことを示します。同じtitleでも、ポイント事業者がコードを返さないエラー(タイムアウト、メンテナンスなど)ではproviderCodeは設定されません- 同じコード値でも、APIによって
titleが異なる場合があります(例:PontaポイントのE090000000、Vポイントの41/42)。providerCodeだけでtitleを判断しないでください - ポイント認可の失敗はポイント認可結果確認(
/point/memberinquiry)API、ポイント付与・ポイント付与取消の失敗はポイント取引照会(/point/inquiry)APIのerrorInformationで返ります - ポイント残高照会(
/point/balance)APIでは、member_terminatedの行のコードはエラーではなく200(pointUsableがfalse)で返ります(後述) invalid_status(Vポイントの22-101)は、通常はポイント認可済みとして成功で返り、エラーにはなりません- ポイント事業者の仕様変更などにより、表にないコードが返る場合があります
ポイント残高照会の特例
ポイント残高照会(/point/balance)APIでは、ポイント事業者がお客様のポイント利用を抑止している場合(お客様が初期状態、ポイント利用停止など)も、照会自体は成立しているため 200 で返ります。
この場合はエラーレスポンスではなく、以下のように返ります。
{
"pointType": "PONTA",
"memberId": "member-001",
"availablePoint": 1400,
"pointUsable": false,
"providerCode": "N058000000-03"
}
pointUsableがfalseのときはポイント利用をお控えください- 残高(
availablePoint)が返っていてもpointUsableがfalseのことがあります - 抑止理由が判別できる場合のみ
providerCodeが設定されます
pointUsable が false のままポイント利用(/point/use)APIを実行しても、ポイント事業者側で拒否され processing_failure となります。
残高照会の結果でポイント利用の入力画面・機能を抑止してください。
お客様の状態の判別
Pontaポイントでは providerCode の末尾でお客様の状態区分を判別できます。
providerCode | お客様の状態 |
|---|---|
N058000000-02 | 初期状態(ポイント利用の申込が未実施) |
N058000000-03 | ポイント利用停止 |
title と detail は両区分で共通のため、区分の判別には providerCode を使用してください。
お客様へ表示するメッセージ
Pontaポイント・Vポイントでは、ポイント事業者が定めたメッセージをお客様へ表示する必要があります。
エラー時に加盟店様が独自に作成した文言を表示することはできません。当社が提示するメッセージ文言をそのまま表示してください。
エラー発生時のロールバック
ポイント利用の後に実行した決済がエラーになった場合は、ポイント利用取消(/point/cancel)APIでポイント利用を取消してください。
ポイント利用APIそのものがエラーになり結果が不明な場合も、ポイント利用取消(/point/cancel)APIで取消できます。
ポイント付与が GRANTFAIL(付与失敗確定)となった場合、ポイントは付与されていないため取消は不要です。