ポイント エラーコード
ポイントの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 | エラーの内容サマリー。エラーコードとして取り扱えます |
detail | エラーの詳細説明（英文） |
instance | エラーが発生したエンドポイント |
providerCode | ポイント事業者が返却した原エラーコード。ポイント事業者起因のエラー時のみ設定されます |
providerCode について
providerCode は、ポイント事業者のAPIが返したコードを 変換せずそのまま 返す項目です。
- コードの体系と意味は ポイント事業者ごとに異なります（例：Pontaポイントの
E052000000、Vポイントの22-101） - ポイント事業者がコードを返さない場合は設定されません
- 当サービスが判定したエラー（パラメーター不正など）では設定されません
providerCode は当サービスでは意味を解釈しないため、加盟店様の処理分岐には title を使用してください。
providerCode は、お客様の画面に表示するメッセージの決定、お客様からの問い合わせ対応、ポイント事業者への調査依頼の際にご利用ください。
providerCode ごとに定められていますPontaポイント・Vポイントでは、ポイント事業者起因のエラー時にお客様へ表示するメッセージがポイント事業者との取り決めで定められています。
事業者エラーメッセージの文言を表示してください。
コードの意味についてお問い合わせが必要な場合は、title・detail・providerCode・accessId をあわせてお問い合わせください。
ポイントのAPIで返るエラー
ポイントのAPIで返る title の一覧です。
400 リクエストパラメーターエラー
| title | 説明 | 加盟店様の対応 |
|---|---|---|
missing_parameter | 必須パラメーターが設定されていません。 ポイント事業者ごとに必須の項目が異なります | detail の項目名を確認し、事業者別の仕様差異を参照して必須パラメーターを設定してください |
invalid_parameter | リクエストパラメーターの書式・桁数が不正です。 ポイント事業者とポイントカテゴリの組み合わせが対応外の場合も含みます | detail の項目名を確認して修正してください |
unsupported_operation | 指定したポイント事業者が対象の操作に対応していません。 ポイント付与の部分取消を指定した場合も含みます | 事業者別の仕様差異で対応APIを確認してください |
approval_not_found | ポイント認可が存在しない、または解除されています | ポイント認可開始（/point/start）APIから認可し直してください |
approval_terminated | ポイント認可が無効、または有効期限切れです | 同上 |
invalid_status | 対象の取引状態に対して処理できないリクエストです。 既に取消済み、取消できない状態、既に認可済みなどの場合に発生します | ポイント取引照会（/point/inquiry）APIで取引状態を確認してください |
transaction_not_found | 対象の取引が存在しません | accessId / orderId を確認してください |
transaction_already_exists | 対象の取引が既に存在します。orderId の重複も含みます | orderId を一意の値にしてください |
transaction_expired | 処理期限を超過しています。 ポイント利用取消・利用ポイント変更の期限超過時に発生します | 元取引の処理可能期間を確認してください |
transaction_count_exceeded | 同一取引に対する処理上限を超過しています。 利用ポイント変更は1取引につき1回まで です | 2回目以降の変更が必要な場合はポイント利用取消（/point/cancel）APIで全額取消のうえ、再度ポイント利用（/point/use）APIを実行してください |
member_not_found | 対象の会員が存在しません | memberId を確認してください |
invalid_contract | 対象ショップの契約状態が無効、またはショップの設定が不足しています | ポイントのご利用契約と設定状況をご確認ください |
402 リクエストエラー（ポイント事業者による拒否）
| title | 説明 | 加盟店様の対応 |
|---|---|---|
insufficient_balance | ポイント残高が不足しています。usePoint が salesAmount を超えた場合も同じエラーが返ります | お客様に残高不足を案内してください。事前にポイント残高照会（/point/balance）APIで利用可能ポイント数を確認することで回避できます。usePoint と salesAmount の関係は加盟店様側でご確認ください |
operation_aborted_by_user | お客様の操作によりポイント認可が中止されました | お客様に中止を案内してください |
processing_failure | ポイント事業者からエラーが返りました。 ポイント口座の利用停止、連携数上限の超過などが含まれます | detail と providerCode を確認してください。お客様側の状態に起因する場合はお客様への案内が必要です |
500 当サービス内部のシステムエラー
| title | 説明 | 加盟店様の対応 |
|---|---|---|
internal_server_error | 当サービスのサーバーで問題が発生しました | 時間をおいて再実行してください。継続する場合はお問い合わせください |
502 外部事業者のシステムエラー
| title | 説明 | 加盟店様の対応 |
|---|---|---|
bad_gateway | ポイント事業者やネットワークで問題が発生しました。 ポイント事業者のタイムアウトも含みます | 時間をおいて再実行してください。処理結果が不明な場合はポイント取引照会（/point/inquiry）APIで状態を確認してください |
maintenance | ポイント事業者がメンテナンス中です | 時間をおいて再実行してください |
ポイント残高照会の特例
ポイント残高照会（/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（付与失敗確定）となった場合、ポイントは付与されていないため取消は不要です。