エラーリファレンス

意味

リクエストのパラメータが仕様を満たしていません。

発生条件

必須項目の欠落・形式不正・範囲外・未対応値のいずれか。details 配列に field（JSON Pointer またはパラメータ名）と code（required / format / range / unsupported_value）が入ります。バッチ名寄せ（POST /v1/batch/match）のボディが5MiBを超えた場合のみ、同じ VALIDATION_ERROR を HTTPステータス413（Payload Too Large）で返します（details の code は range）。それ以外は400です。

回復手順

• レスポンスの details を参照し、該当フィールドを修正して再送してください。

• 413（5MiB超過）の場合は入力を分割し、1リクエストあたり5MiB以下に収めて再送してください。

• リトライ不可（retryable: false）です。入力を直さない限り同じエラーになります。

意味

APIキーによる認証に失敗しました。

発生条件

x-api-key ヘッダーが未指定・無効・失効済みのとき。プラン特定不能のためレート制限・クォータヘッダーは送出されません。

回復手順

• x-api-key ヘッダーに有効なAPIキーを指定しているか確認してください。

• キーが失効している場合はダッシュボードのAPIキー画面（/dashboard/api-keys）で再発行してください。

意味

認証は成功していますが、この操作の権限がありません。

発生条件

認可起因の拒否専用です。プラン起因の拒否は PLAN_UPGRADE_REQUIRED として分離されます。

回復手順

• 対象リソースへのアクセス権を持つAPIキーで再試行してください。

• リトライ不可（retryable: false）です。

意味

現在のプランではこの機能を利用できません。

発生条件

上位プラン限定のエンドポイント（バッチ名寄せ等）を下位プランのキーで呼び出したとき。

回復手順

• 料金ページ（/pricing）で必要なプランへ変更してください。

• リトライ不可（retryable: false）です。プラン変更後に再試行してください。

意味

同一の Idempotency-Key を、内容の異なるリクエストで再送しました。

発生条件

既に使用済みの冪等キーで、初回とペイロードが一致しないリクエストを送ったとき。

回復手順

• 同一の Idempotency-Key は必ず同一ペイロードで再送してください。

• 内容が異なる新しいリクエストには別の冪等キーを発行してください。

意味

課金操作が現在のサブスクリプション状態と競合しています。

発生条件

現在の契約状態では実行できない課金操作を要求したとき。

回復手順

• ダッシュボードで現在のサブスクリプション状態を確認してから操作し直してください。

• リトライ不可（retryable: false）です。

意味

現在のアカウント状態では退会（削除）を実行できません。

発生条件

有効なサブスクリプションや未完了処理など、削除を妨げる状態が残っているとき。

回復手順

• 先行して必要な解約・処理完了を行ってから、退会を再実行してください。

• リトライ不可（retryable: false）です。

意味

対象アカウントは既に削除済みです。

発生条件

削除済みアカウントに対して再度削除等の操作を要求したとき。

回復手順

• アカウントは既に削除されています。追加の操作は不要です。

• リトライ不可（retryable: false）です。

意味

この操作には直近の再認証が必要です。

発生条件

次の2ケースで返ります。(a) 削除用の再認証エンドポイント自体が失敗したとき（POST /v1/account/deletion-reauth/password のパスワード不一致、Googleコールバックの state・本人性の不一致、POST /v1/account/deletion-reauth/google/exchange のコード無効・期限切れ等）。(b) 退会（POST /v1/account/deletion）で削除用の再認証チャレンジ（deletion_challenge_token）が未指定・無効・期限切れのとき。いずれも単に再ログインしても同じ403が続きます。

回復手順

• (a) 再認証エンドポイント自体が403の場合は、正しい資格情報（正しいパスワード）またはGoogleのフローをやりなおしてください。Googleは POST /v1/account/deletion-reauth/google/start で発行された state とコールバックの本人性が一致する状態で最初からやり直す必要があります。

• (b) deletion（POST /v1/account/deletion）が403の場合は、パスワードなら POST /v1/account/deletion-reauth/password、Googleなら POST /v1/account/deletion-reauth/google/start → コールバック → POST /v1/account/deletion-reauth/google/exchange の順で deletion_challenge_token を取り直してください。

• 取り直した deletion_challenge_token を POST /v1/account/deletion のボディに付けて、期限内に再試行してください。

• リトライ不可（retryable: false）です。正しい資格情報・フロー、または有効な deletion_challenge_token がない限り同じエラーになります。

意味

バッチジョブがまだ完了していません。

発生条件

status が queued / processing のジョブに対して結果ダウンロードを要求したとき。

回復手順

• GET /v1/batch/{job_id} で終端状態（status: completed または status: failed）になるまでポーリングしてください。queued / processing の間は結果を取得できません。

• completed なら結果をダウンロードしてください。failed なら BATCH_FAILED の回復手順に従って新規ジョブを投入してください。

• リトライ不可（retryable: false）です。終端状態に達してから取得し直してください。

意味

バッチジョブの処理が失敗しました。

発生条件

status が failed のジョブに対して結果ダウンロードを要求したとき。

回復手順

• failedジョブの error.retryable を確認してください。true（ワーカー側の一過性失敗）の場合は同一入力で再投入できます。false の場合のみ入力データを見直してから再投入してください。

• 再投入時は新しいジョブを作成させるため、元の投入で付けた Idempotency-Key を変更するか省略してください。同一キーは保存期間（24時間）内は失敗ジョブの受付応答をリプレイするだけで、新しいジョブは作成されません。

• 失敗した同一ジョブ自体は再実行できません。復旧はいずれの場合も新規ジョブの投入で行います。

意味

指定したリソースが存在しません。

発生条件

存在しない法人番号・登録番号・ジョブID等を指定したとき。

回復手順

• パスやパラメータの識別子が正しいか確認してください。

• リトライ不可（retryable: false）です。

意味

このエンドポイントはまだ実装されていません。

発生条件

未提供の機能を呼び出したとき。

回復手順

• 最新のAPIドキュメントで提供済みのエンドポイントを利用してください。

• リトライ不可（retryable: false）です。

意味

短時間（分単位rpm）のリクエスト上限を超えました。

発生条件

分単位のレート上限に達したとき。ボディは limit_scope: "rpm" と retry_after（既定60秒）を持ちます。現在のレート枠は X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset（Reset はepoch秒）ヘッダーで返します。

回復手順

• ボディの retry_after（既定60秒。Retry-After ヘッダーにも同値が入ります）だけ待ってから再試行してください。

• リトライ可能（retryable: true）です。指数バックオフの併用を推奨します。

意味

月次のクォータ（利用上限）を使い切りました。

発生条件

月次 api_requests または batch_rows の上限に達したとき。ボディの limit_scope にどちらの枠かが入り、retry_after に次サイクルまでの秒数が入ります。api_requests 枠の残量は X-Quota-Limit / X-Quota-Remaining ヘッダーで返します（batch_rows 枠にはヘッダーがなく、上限超過は limit_scope で判別します）。

回復手順

• ボディの retry_after（次サイクルのリセットまでの秒数）だけ待つか、料金ページ（/pricing）で上位プランへ変更してください。

• リトライ可能（retryable: true）ですが、枠が回復するまでは同じエラーになります。

意味

依存するバックエンド基盤が一時的に利用できません。

発生条件

認証・クォータ・冪等性・リポジトリ操作などが依存するバックエンド基盤（データベース・キャッシュ等）に一時的な障害・遅延が発生したとき。

回復手順

• Retry-After（既定30秒）を目安に短いバックオフを置いて再試行してください。

• リトライ可能（retryable: true）です。多くは一過性で自然回復します。

意味

サーバー内部で予期しないエラーが発生しました。

発生条件

上記いずれにも該当しない未分類のサーバー側エラー。

回復手順

• 自動リトライはしないでください。機械可読契約は retryable: false（retry_after も null）です。即時に再試行すると二重実行やリトライストームを招きます。

• 時間をおいて操作をやり直す場合は冪等性に注意してください。バッチ投入などでは Idempotency-Key を活用し、同一操作の重複作成を防いでください。

• 継続する場合はサポートへ問い合わせてください。