コンテンツにスキップ

運用

エラーとレート制限

すべてのエンドポイント(月例給与の計算・賞与の計算・シミュレーション・マスタ照会)は、エラー時に共通の形式でJSONを返します。このページでは、その形式と主要なエラーコードをまとめて解説します。

{
"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.details422 validation_error のときのみ検証に失敗したフィールドの一覧(後述)。
ステータスerror.code意味対処
401unauthorizedX-API-Key ヘッダーが未指定、または無効です発行済みのAPIキーを X-API-Key ヘッダーに設定してください。詳細は 認証 を参照
402quota_exceeded無料プランの当月の計算回数の上限に達しました(アカウント単位)。月例給与・賞与の計算エンドポイント(/v1/payroll/*)にのみ適用され、シミュレーション・マスタ照会エンドポイントは対象外ですプランのアップグレードを検討するか、翌月(JST暦月)の上限リセットを待ってください
403account_suspendedAPIキー自体は有効だが、紐づくアカウントが停止中(お支払い状況の問題など)ですダッシュボードでアカウントの課金状態を確認し、必要な対応(お支払い方法の更新など)を行ってください
403insufficient_scopeAPIキーは有効・アカウントも正常だが、呼び出したエンドポイントに必要なスコープを持っていませんダッシュボードで発行し直したAPIキーに、必要なスコープ(計算API用・シミュレーション用・マスタ参照用など)が含まれているか確認してください
404company_not_found会社がこのアカウントに存在しませんcompany_id を確認してください。他アカウントの company_id や存在しないIDを指定した場合に返ります
409settings_lock_conflictリクエストの settings_lock が、実際に解決された設定バージョンと一致しませんsettings_lock を外すか、現在有効な設定バージョンで再送してください
422validation_errorリクエストボディがスキーマ検証に失敗しましたdetails を確認し、対象フィールドを修正してください(後述)
422settings_not_resolved指定した company_id と payment_date の組み合わせで、有効な会社計算プロファイルが解決できません会社の社会保険設定(都道府県・保険料率)がダッシュボードで完了しているか、payment_date が設定の有効期間内かを確認してください
422income_tax_lookup_failed解決された法令マスタ(税額表)に必要な行・ブラケットがなく、所得税を計算できません。通常の運用では発生せず、法令マスタの不備・未整備時に限られますrequest_id と発生日時を添えて問い合わせてください。月額表では通常の row 範囲外も本表ブラケットで計算されるため、給与額を下げて回避する必要はありません
422withholding_rate_override_not_allowed(賞与のみ)会社プロファイルで allow_withholding_rate_override が有効でないのに、源泉税率の上書きを指定しました上書きを使わないか、ダッシュボードで会社プロファイルの設定を確認してください
422attendance_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 を外してください
422attendance_rates_not_configured(月例給与のみ)解決された会社プロファイルに勤怠割増率4種が設定されていません。message: Attendance premium rates are not configured for the resolved company profile.ダッシュボードで勤怠割増率4種を設定し、そのプロファイルが payment_date に有効か確認してください
422negative_gross_payment(月例給与のみ)勤怠由来の控除によって gross_payment が負になります。message: Attendance-derived deductions make gross_payment negative.attendance_input の欠勤・遅刻早退分数、基本給、対象手当を確認してください
422negative_social_insurance_deductions(月例給与のみ)当月の社会保険料等(5項目)と過去月差額の合計がマイナスです。message: Social insurance deductions must not be negative. Split refunds across multiple months.還付を複数月に分け、各月の合計が 0 以上になるようにしてください
429rate_limit_exceededレート制限を超過しました(後述)Retry-After ヘッダーの秒数だけ待ってから再試行してください
404not_found未定義のルートですURLとHTTPメソッドを確認してください
500internal_errorエンジン側の未処理例外です少し待って再試行し、継続する場合は request_id と発生日時を添えて問い合わせてください
503service_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意味対処
422company_limit_reached現在のプランで登録できる会社数の上限に達しています複数の会社を管理する場合はEnterpriseプランへアップグレードしてください。ダッシュボードではサーバーのエラーメッセージも表示されます
422plan_not_billableBaseeプランなど、ダッシュボードから課金プランを変更できないアカウントでcheckoutを開始しようとしましたBaseeプランの変更はBasee連携側で管理されます。通常、ダッシュボードにはcheckout操作が表示されません

未定義ルート・未処理例外のレスポンス

Section titled “未定義ルート・未処理例外のレスポンス”

アプリケーション(Hono)の未定義ルートは 404 not_found、未処理例外は 500 internal_error を返します。いずれも Content-Type: application/json の共通形式で、request_id が付与されます。内部の例外メッセージやスタックは返しません。

ステータスerror.codeerror.message
404not_foundThe requested resource was not found.
500internal_errorInternal server error.

公開APIホストやダッシュボードのAPI経路では、nginx が生成する次のエラーも Content-Type: application/json で返します。形式は {"error":{"code":"...","message":"..."}} で、request_id は付与されません。アプリケーションが返したエラーは nginx で上書きされません。

対象ステータスerror.codeerror.message
公開APIホストの未定義パス404not_foundThe requested resource was not found.
公開されていないパス403forbiddenThis endpoint is not available on this host.
公開API、ダッシュボードの /cp/v1/ の本文サイズ超過413payload_too_largeRequest body is too large.
公開API、ダッシュボードの /cp/v1/ の接続先サービス障害502・503・504service_unavailableThe 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 が設定の有効期間から外れている場合に発生します。

会社が計算できない状態のときは、まずダッシュボードで社会保険設定(都道府県・協会けんぽプリセットまたは独自料率)が完了しているかを確認してください。

計算・マスタ照会APIには、悪用防止のためのレート制限があります。

  • APIキーで認証されたリクエストは、アカウント単位でカウントされます(同じアカウントの複数キー・複数サーバーからの呼び出しは合算されます)。
  • 制限に達すると 429 とともに error.code: "rate_limit_exceeded" が返り、レスポンスヘッダーに Retry-After(あと何秒待てば再試行できるか、秒数)が付与されます。
  • 再試行する際は Retry-After の秒数だけ待ってから送信してください。即座にリトライを繰り返すと、制限がリセットされるまでさらに遠のきます。

アプリケーション由来のエラーには、未定義ルートの 404 や未処理例外の 500 を含め、error.request_id が付与されます。挙動について問い合わせる際は、発生日時とあわせて request_id を伝えてください。個々のリクエストを一意に特定できるため、調査が早くなります。nginx 由来のエラーには request_id がないため、発生日時・接続先ホスト・ステータス・エラーコードを伝えてください。個人情報やAPIキーは問い合わせに含めないでください。