運用
エラーとレート制限
すべてのエンドポイント(月例給与の計算・賞与の計算・シミュレーション・マスタ照会)は、エラー時に共通の形式でJSONを返します。このページでは、その形式と主要なエラーコードをまとめて解説します。
エラーレスポンスの形式
Section titled “エラーレスポンスの形式”{ "error": { "code": "validation_error", "message": "Request validation failed.", "request_id": "075cbd87-37ea-48eb-9850-56fc4684bb5f", "details": [ { "path": ["company_id"], "code": "invalid_type" } ] }}| フィールド | 必須 | 説明 |
|---|---|---|
error.code | 必須 | 機械可読なエラーコード(下表を参照)。分岐処理には error.code を使ってください。 |
error.message | 必須 | 人間可読な説明文。英語です。 |
error.request_id | アプリケーション由来のエラーに付与 | このリクエストを一意に識別するID。500 internal_error にも付与されます。nginx 由来のエラーには付与されません。 |
error.details | 422 validation_error のときのみ | 検証に失敗したフィールドの一覧(後述)。 |
主要なエラー
Section titled “主要なエラー”| ステータス | error.code | 意味 | 対処 |
|---|---|---|---|
401 | unauthorized | X-API-Key ヘッダーが未指定、または無効です | 発行済みのAPIキーを X-API-Key ヘッダーに設定してください。詳細は 認証 を参照 |
402 | quota_exceeded | 無料プランの当月の計算回数の上限に達しました(アカウント単位)。月例給与・賞与の計算エンドポイント(/v1/payroll/*)にのみ適用され、シミュレーション・マスタ照会エンドポイントは対象外です | プランのアップグレードを検討するか、翌月(JST暦月)の上限リセットを待ってください |
403 | account_suspended | APIキー自体は有効だが、紐づくアカウントが停止中(お支払い状況の問題など)です | ダッシュボードでアカウントの課金状態を確認し、必要な対応(お支払い方法の更新など)を行ってください |
403 | insufficient_scope | APIキーは有効・アカウントも正常だが、呼び出したエンドポイントに必要なスコープを持っていません | ダッシュボードで発行し直したAPIキーに、必要なスコープ(計算API用・シミュレーション用・マスタ参照用など)が含まれているか確認してください |
404 | company_not_found | 会社がこのアカウントに存在しません | company_id を確認してください。他アカウントの company_id や存在しないIDを指定した場合に返ります |
409 | settings_lock_conflict | リクエストの settings_lock が、実際に解決された設定バージョンと一致しません | settings_lock を外すか、現在有効な設定バージョンで再送してください |
422 | validation_error | リクエストボディがスキーマ検証に失敗しました | details を確認し、対象フィールドを修正してください(後述) |
422 | settings_not_resolved | 指定した company_id と payment_date の組み合わせで、有効な会社計算プロファイルが解決できません | 会社の社会保険設定(都道府県・保険料率)がダッシュボードで完了しているか、payment_date が設定の有効期間内かを確認してください |
422 | income_tax_lookup_failed | 解決された法令マスタ(税額表)に必要な行・ブラケットがなく、所得税を計算できません。通常の運用では発生せず、法令マスタの不備・未整備時に限られます | request_id と発生日時を添えて問い合わせてください。月額表では通常の row 範囲外も本表ブラケットで計算されるため、給与額を下げて回避する必要はありません |
422 | withholding_rate_override_not_allowed(賞与のみ) | 会社プロファイルで allow_withholding_rate_override が有効でないのに、源泉税率の上書きを指定しました | 上書きを使わないか、ダッシュボードで会社プロファイルの設定を確認してください |
422 | attendance_input_conflict(月例給与のみ) | attendance_input と計算済み勤怠金額を併用しています。message: attendance_input cannot be combined with non-zero calculated attendance amounts. | overtime_pay・absence_deduction・late_early_leave_deduction をすべて 0 にするか、attendance_input を外してください |
422 | attendance_rates_not_configured(月例給与のみ) | 解決された会社プロファイルに勤怠割増率4種が設定されていません。message: Attendance premium rates are not configured for the resolved company profile. | ダッシュボードで勤怠割増率4種を設定し、そのプロファイルが payment_date に有効か確認してください |
422 | negative_gross_payment(月例給与のみ) | 勤怠由来の控除によって gross_payment が負になります。message: Attendance-derived deductions make gross_payment negative. | attendance_input の欠勤・遅刻早退分数、基本給、対象手当を確認してください |
422 | negative_social_insurance_deductions(月例給与のみ) | 当月の社会保険料等(5項目)と過去月差額の合計がマイナスです。message: Social insurance deductions must not be negative. Split refunds across multiple months. | 還付を複数月に分け、各月の合計が 0 以上になるようにしてください |
429 | rate_limit_exceeded | レート制限を超過しました(後述) | Retry-After ヘッダーの秒数だけ待ってから再試行してください |
404 | not_found | 未定義のルートです | URLとHTTPメソッドを確認してください |
500 | internal_error | エンジン側の未処理例外です | 少し待って再試行し、継続する場合は request_id と発生日時を添えて問い合わせてください |
503 | service_unavailable | 認証情報の検証処理自体が一時的に利用できません(DB障害など) | 少し待って再試行してください。継続する場合は発生日時を添えて問い合わせてください |
計算API(/v1/...)自身が返す主な 403 は上表の account_suspended と insufficient_scope の2つだけです。これとは別に email_verification_required というエラーコードもありますが、こちらは計算APIのエラーではなく、ダッシュボードでAPIキーを発行しようとした際に、アカウントのメールアドレス認証が未完了だと返るエラーです。詳細は 認証 を参照してください。
ダッシュボード(/cp/v1)のプラン関連エラー
Section titled “ダッシュボード(/cp/v1)のプラン関連エラー”次のエラーは公開計算API(/v1)ではなく、ダッシュボードが使うコントロールプレーンAPI(/cp/v1)から返ります。上の公開APIの主要エラー一覧とは別に扱ってください。
| ステータス | error.code | 意味 | 対処 |
|---|---|---|---|
422 | company_limit_reached | 現在のプランで登録できる会社数の上限に達しています | 複数の会社を管理する場合はEnterpriseプランへアップグレードしてください。ダッシュボードではサーバーのエラーメッセージも表示されます |
422 | plan_not_billable | Baseeプランなど、ダッシュボードから課金プランを変更できないアカウントでcheckoutを開始しようとしました | Baseeプランの変更はBasee連携側で管理されます。通常、ダッシュボードにはcheckout操作が表示されません |
未定義ルート・未処理例外のレスポンス
Section titled “未定義ルート・未処理例外のレスポンス”アプリケーション(Hono)の未定義ルートは 404 not_found、未処理例外は 500 internal_error を返します。いずれも Content-Type: application/json の共通形式で、request_id が付与されます。内部の例外メッセージやスタックは返しません。
| ステータス | error.code | error.message |
|---|---|---|
404 | not_found | The requested resource was not found. |
500 | internal_error | Internal server error. |
nginx 由来のエラー
Section titled “nginx 由来のエラー”公開APIホストやダッシュボードのAPI経路では、nginx が生成する次のエラーも Content-Type: application/json で返します。形式は {"error":{"code":"...","message":"..."}} で、request_id は付与されません。アプリケーションが返したエラーは nginx で上書きされません。
| 対象 | ステータス | error.code | error.message |
|---|---|---|---|
| 公開APIホストの未定義パス | 404 | not_found | The requested resource was not found. |
| 公開されていないパス | 403 | forbidden | This endpoint is not available on this host. |
公開API、ダッシュボードの /cp/v1/ の本文サイズ超過 | 413 | payload_too_large | Request body is too large. |
公開API、ダッシュボードの /cp/v1/ の接続先サービス障害 | 502・503・504 | service_unavailable | The service is temporarily unavailable. Please retry later. |
403 は接続先ホストとパス、413 はリクエスト本文のサイズを確認してください。502・503・504 は少し待って再試行し、継続する場合は発生日時とステータスを添えて問い合わせてください。
422 validation_error の details の読み方
Section titled “422 validation_error の details の読み方”details は、検証に失敗したフィールドごとに path と code を持つ配列です。
"details": [ { "path": ["company_id"], "code": "invalid_type" }, { "path": ["calculation_date"], "code": "invalid_type" }, { "path": ["period"], "code": "invalid_type" }, "..."]上記は抜粋です。実際に空ボディを送信した場合、全6件(company_id/calculation_date/payment_date/period/employee_snapshot/base_pay)が列挙されます。
path— 失敗したフィールドへの経路を、リクエストボディのキー名を並べた配列で表します。例えば["employee_snapshot", "tax_dependent_count"]は、employee_snapshot.tax_dependent_countが検証に失敗したことを示します。code— 検証ライブラリ(Zod)が返す失敗種別です。フィールドが未指定・型不一致の場合はinvalid_type、文字列の形式が合わない場合はinvalid_stringなど、pathが指すフィールドの制約に応じたコードが入ります。
複数フィールドが同時に失敗した場合、details にはすべての失敗が列挙されます。最初の1件だけを見て対応するのではなく、配列全体を確認してください。
404 と 422 settings_not_resolved の違い
Section titled “404 と 422 settings_not_resolved の違い”どちらも「この company_id では計算できない」という結果になりますが、原因が異なります。
404 company_not_found—company_idそのものが、このAPIキーのアカウントに存在しません(タイプミス・他アカウントのIDを指定した場合など)。422 settings_not_resolved—company_idは存在するが、指定したpayment_dateの時点で有効な会社計算プロファイル(都道府県・社会保険料率などの設定)が解決できません。会社作成直後で社会保険設定がまだ完了していない場合や、payment_dateが設定の有効期間から外れている場合に発生します。
会社が計算できない状態のときは、まずダッシュボードで社会保険設定(都道府県・協会けんぽプリセットまたは独自料率)が完了しているかを確認してください。
レート制限(429)
Section titled “レート制限(429)”計算・マスタ照会APIには、悪用防止のためのレート制限があります。
- APIキーで認証されたリクエストは、アカウント単位でカウントされます(同じアカウントの複数キー・複数サーバーからの呼び出しは合算されます)。
- 制限に達すると
429とともにerror.code: "rate_limit_exceeded"が返り、レスポンスヘッダーにRetry-After(あと何秒待てば再試行できるか、秒数)が付与されます。 - 再試行する際は
Retry-Afterの秒数だけ待ってから送信してください。即座にリトライを繰り返すと、制限がリセットされるまでさらに遠のきます。
request_id を添えて問い合わせる
Section titled “request_id を添えて問い合わせる”アプリケーション由来のエラーには、未定義ルートの 404 や未処理例外の 500 を含め、error.request_id が付与されます。挙動について問い合わせる際は、発生日時とあわせて request_id を伝えてください。個々のリクエストを一意に特定できるため、調査が早くなります。nginx 由来のエラーには request_id がないため、発生日時・接続先ホスト・ステータス・エラーコードを伝えてください。個人情報やAPIキーは問い合わせに含めないでください。
- 認証 —
X-API-Keyの扱いとAPIキー発行の前提条件 - リファレンス概要 — エラー形式の概要とベースURL
- マスタとバージョン解決 —
settings_not_resolvedの背景にある設定解決の仕組み