エラーコード

Push! Passkey APIと顧客サイト側で発生するエラーを確認する

このページでは、現在稼働しているPush! Passkeyの実装を正式仕様として、URL発行API、結果照会API、顧客サイトのバックエンド、利用者画面で扱うエラーコードを説明します。

エラー発生時は、プログラム側ではerror_codeを使って処理を分岐し、利用者画面には分かりやすい日本語メッセージを表示します。

APIキー、内部URL、SQL、サーバのファイルパス、スタックトレース、APIの生レスポンスは利用者画面へ表示しないでください。

同じエラーコードでも、発生したAPI、HTTPステータス、処理段階によって確認内容が異なります。ログにはrequest_id、処理種別、HTTPステータス、error_code、発生日時を記録してください。

• 共通エラーレスポンス
• URL発行APIのエラー
• 結果照会APIのエラー
• 顧客バックエンドエンドポイントのエラー
• 通信・HTTP・JSONのエラー
• 利用者向けメッセージ
• 再試行できるエラーとできないエラー
• ログへ記録する情報

1. 共通エラーレスポンス

基本形式

{
	"ok": false,
	"error_code": "invalid_api_key",
	"message": "APIキーが正しくありません。"
}

利用者向け表示と内部ログを分ける

APIから返されたmessageをそのまま利用者へ表示するのではなく、顧客サイト側で用途に応じた日本語メッセージへ置き換える方法を推奨します。

内部ログには調査に必要な情報を記録し、画面には次の行動が分かる内容だけを表示します。

2. エラーの分類

3. URL発行APIのエラーコード

登録URL発行APIと認証URL発行APIで確認されているエラーコードです。

api_key_required

APIキーは顧客サイトのバックエンドで設定します。

$api_request = [
	'api_key' => $config['api_key'],
	'user_key' => $user_key,
	'return_page_url' => $return_page_url,
];

ブラウザから受け取った値をAPIキーとして使用しないでください。

user_key_required

登録処理では、ログイン中のユーザーを顧客サイトのセッションから取得します。

認証開始時に利用者がメールアドレスなどを入力する構成でも、顧客DBで対象ユーザーを検索し、Push! Passkey連携用のuser_keyへ変換してください。

invalid_api_key

次の項目を確認します。

• 開発環境用と本番環境用のAPIキーを取り違えていない
• APIキーの前後に空白や改行が含まれていない
• 対象ドメインが管理ツールで有効になっている
• 削除または再発行済みの古いAPIキーを使用していない
• JSON項目名がapi_keyになっている

4. 結果照会APIのエラーコード

登録結果照会APIと認証結果照会APIで確認されているエラーコードです。

5. request_not_found

主な原因

• URL発行APIから返されたrequest_idを保存していない
• request_idの一部が欠落している
• URLパラメータのpp_request_idが変更されている
• 開発環境のrequest_idを本番環境で照会している
• 存在しない値を手動で指定している

確認方法

URL発行APIのレスポンスを受け取った時点で、次の情報を顧客サイトのセッションまたはDBへ保存してください。

[
	'request_id' => $request_id,
	'kind' => $kind,
	'user_key' => $user_key,
	'expire_at' => $expire_at,
	'used' => false,
]

リダイレクト後に受け取ったpp_request_idは、保存済みの値と一致することを確認します。

6. request_domain_mismatch

APIキーとrequest_idの組み合わせが一致しない

URL発行時に使用したAPIキーと、結果照会時に使用したAPIキーが異なるドメインに属している場合に発生します。

主な原因

• 複数顧客のAPIキーを設定ファイルで取り違えている
• 開発・検証・本番環境の設定が混在している
• 別ドメインで発行したrequest_idを照会している
• マルチテナント処理でAPIキーの選択を誤っている

対応

request_idを保存するときに、顧客サイト側のテナントIDや対象ドメインも一緒に保存し、結果照会時に同じ設定を使用してください。

7. request_kind_mismatch

登録と認証の結果照会先が一致しない

URL発行時にkindを保存し、その値から結果照会先を固定的に決定します。

$api_url = match ($kind) {
	'regist' => $config['regist_result_api'],
	'auth' => $config['auth_result_api'],
};

ブラウザから受け取ったpp_kindだけで結果照会先を決定せず、顧客サイト側で保存したkindと照合してください。

8. REQUEST_EXPIRED

有効期限は発行から10分

登録URLと認証URLの有効期限は、現在の正式仕様では発行から10分間です。

期限切れ後は古いURLやrequest_idを再利用せず、新しいURLを発行してください。

利用者向け表示例

「認証の有効時間が終了しました。最初からやり直してください。」

自動再試行しない

期限切れのrequest_idを使って結果照会を繰り返しても成功しません。

顧客サイト側でポーリングしている場合は、expiredまたはREQUEST_EXPIREDを受け取った時点でポーリングを停止します。

9. 顧客バックエンドのエラーコード

次のエラーコードは、顧客サイトのバックエンドで入力、認証状態、セッションを検証するときに使用する例です。

許可するaction

• regist_start
• auth_start
• regist_result
• auth_result

server_error

利用者には内部詳細を表示せず、問い合わせ用の受付番号を返します。

{
	"ok": false,
	"error_code": "server_error",
	"message": "処理を完了できませんでした。受付番号：a1b2c3d4"
}

10. 通信・HTTP・JSONエラー

HTML応答を成功として扱わない

try {
	$response = json_decode(
		$response_body,
		true,
		512,
		JSON_THROW_ON_ERROR
	);
} catch (JsonException $e) {
	throw new RuntimeException(
		'Push! Passkey APIの応答がJSONではありません。'
	);
}

Webサーバの405や500ページがHTMLで返された場合も、API成功として扱わないでください。

11. 利用者向けメッセージ

表示しない情報

• APIキー
• SQL文
• DB接続情報
• サーバのファイルパス
• スタックトレース
• cURLの詳細エラー全文
• APIの生レスポンス

12. 再試行方針

URL発行APIがタイムアウトした場合、Push! Passkey側でリクエスト保存まで完了している可能性があります。

無条件に連続再送せず、顧客サイト側で二重送信防止と受付ログを実装してください。

13. ログ設計

記録する情報

• 発生日時
• 顧客サイト側の受付番号
• request_id
• actionまたはkind
• 接続したAPI
• HTTPステータス
• error_code
• 処理段階
• 再試行回数

記録しない情報

• APIキー
• Cookie
• セッションID
• パスワード
• 秘密鍵
• 不要な個人情報

14. エラー処理の実装例

error_codeで分岐する

$error_code =
	$response['error_code'] ?? 'unknown_error';

$user_message = match ($error_code) {
	'REQUEST_EXPIRED' =>
		'認証の有効時間が終了しました。'
		. '最初からやり直してください。',

	'request_not_found',
	'request_domain_mismatch',
	'request_kind_mismatch' =>
		'認証結果を確認できませんでした。'
		. '最初からやり直してください。',

	'invalid_api_key',
	'api_key_required' =>
		'現在この機能を利用できません。'
		. '管理者へお問い合わせください。',

	default =>
		'処理を完了できませんでした。'
		. '時間をおいて再度お試しください。',
};

内部ログへ記録する

error_log(json_encode([
	'timestamp' => date('c'),
	'request_id' => $request_id,
	'kind' => $kind,
	'http_status' => $http_status,
	'error_code' => $error_code,
], JSON_UNESCAPED_UNICODE));

APIキーやCookieをログ配列へ追加しないでください。

15. 動作確認

URL発行API

• api_key未指定時にapi_key_requiredを処理できる
• user_key未指定時にuser_key_requiredを処理できる
• 不正なAPIキーでinvalid_api_keyを処理できる
• DBエラーを利用者へ詳細表示しない

結果照会API

• request_id未指定時にrequest_id_requiredを処理できる
• 存在しないrequest_idを拒否できる
• ドメイン不一致を拒否できる
• kind不一致を拒否できる
• 期限切れ時に新しいURL発行へ案内できる

顧客バックエンドエンドポイント

• GET要求を405で拒否できる
• JSON以外を拒否できる
• 不正なactionを拒否できる
• 未ログイン登録を拒否できる
• CSRF不一致を拒否できる

表示とログ

• 利用者画面にAPIキーが表示されない
• APIの生レスポンスが表示されない
• 内部ログにrequest_idとerror_codeが記録される
• 内部ログにAPIキーやCookieが記録されない

16. 次に確認するページ

トラブルシューティング

HTTP 405、JSONではない応答、APIキー不正、結果照会できない場合の具体的な確認手順を案内します。

トラブルシューティングを読む

APIリファレンス

各APIの正式なURL、リクエスト項目、レスポンス項目を確認します。

APIリファレンスを読む

認証結果の受け取り

request_id、kind、user_key、statusの照合とセッション発行を確認します。

認証結果の受け取りを読む

まとめ

error_codeを処理判断と調査に使用する

Push! Passkey APIでエラーが発生した場合は、HTTPステータスとJSON本文のerror_codeを確認します。

URL発行APIでは、APIキー、user_key、ドメイン情報、リクエスト保存に関するエラーが発生します。

結果照会APIでは、request_id、ドメイン、処理種別、有効期限、DB取得に関するエラーが発生します。

利用者向けには再試行方法が分かるメッセージを表示し、内部ログにはrequest_id、kind、HTTP、error_code、発生日時を記録してください。

APIキー、Cookie、パスワード、内部構成情報は、画面にもログにも出力しないでください。