コンテンツにスキップ

運用

エラーとレート制限

すべてのエンドポイント(月例給与の計算・賞与の計算・シミュレーション・マスタ照会)は、エラー時に共通の形式で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_id500 以外は付与このリクエストを一意に識別するID。問い合わせ時に添えてください(後述)。500 では付与されない場合があります。
error.details422 validation_error のときのみ検証に失敗したフィールドの一覧(後述)。

主要なエラー

Section titled “主要なエラー”
ステータス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 の欠勤・遅刻早退分数、基本給、対象手当を確認してください
429rate_limit_exceededレート制限を超過しました(後述)Retry-After ヘッダーの秒数だけ待ってから再試行してください
500―エンジン側の内部エラー一時的な場合は再試行してください(下記「500 のレスポンス形式」を参照)
503service_unavailable認証情報の検証処理自体が一時的に利用できません(DB障害など)少し待って再試行してください。継続する場合は発生日時を添えて問い合わせてください

403 は3種類ありますが、計算API(/v1/...)自身が返すのは上表の 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操作が表示されません

500 のレスポンス形式について

Section titled “500 のレスポンス形式について”

500 は、想定外の内部エラーが発生した場合のフォールバックです。他のエラーと異なり、JSON封筒(error.code/request_idなど)が付与されずプレーンテキストで返る場合があります。想定済みのエラー(上表の401〜429)はすべてJSON封筒付きで返りますが、アプリケーションが明示的にハンドリングしていない例外は、この形式に頼らずフレームワークの既定応答になるためです。問い合わせる際は request_id に頼らず、発生日時と**送信したリクエストの内容(個人情報・APIキーを除く)**を添えてください。

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 を添えて問い合わせる”

想定済みのエラー(上表の 500 以外)には error.request_id が付与されます。挙動について問い合わせる際は、発生日時とあわせて request_id を伝えてください。個々のリクエストを一意に特定できるため、調査が早くなります。ただし 500 はこの限りではありません(上記「500 のレスポンス形式について」を参照)。

関連リンク

Section titled “関連リンク”