---
title: "IRS retirement & HSA contribution limits for a person/year"
method: POST
path: "/v1/contribution-limits"
tags: ["Utilities"]
---

# IRS retirement & HSA contribution limits for a person/year

`POST /v1/contribution-limits`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/contribution-limits`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Returns the contribution limits that apply to a given person in a given year: the §402(g) elective-deferral limit and the age-appropriate catch-up (auto-selecting the SECURE 2.0 ages-60-63 super catch-up), the IRA limit, the §415(c) annual-additions ceiling, SIMPLE and SEP limits, and the HSA limit — each capped at compensation where applicable. Also flags the SECURE 2.0 §603 Roth catch-up mandate. Year-keyed IRS tables. Deterministic.

## Request body

- ContributionLimitsRequest
  - `tax_year` 2025 | 2026, required
  - `age` integer, required
  - `compensation` number, required: Earned income / plan compensation; caps the contribution maxima.
  - `prior_year_wages` number: Optional. Prior-year FICA wages, for the SECURE 2.0 §603 Roth catch-up mandate (2026+).
  - `hsa_coverage` 'none' | 'self' | 'family'
  - `elective_deferral_ytd` number: Optional. 401(k)-type deferrals so far this year, for remaining headroom.
  - `ira_contribution_ytd` number
  - `hsa_contribution_ytd` number
  - `employer_match_rate` number: Optional. Employer matches this fraction of employee deferrals (e.g. 0.5).
  - `employer_match_cap_pct` number: Match applies up to this fraction of compensation (e.g. 0.06).

## Response `200`

Applicable contribution limits

- ContributionLimitsResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` ContributionLimitsRequest
    - `tax_year` 2025 | 2026, required
    - `age` integer, required
    - `compensation` number, required: Earned income / plan compensation; caps the contribution maxima.
    - `prior_year_wages` number: Optional. Prior-year FICA wages, for the SECURE 2.0 §603 Roth catch-up mandate (2026+).
    - `hsa_coverage` 'none' | 'self' | 'family'
    - `elective_deferral_ytd` number: Optional. 401(k)-type deferrals so far this year, for remaining headroom.
    - `ira_contribution_ytd` number
    - `hsa_contribution_ytd` number
    - `employer_match_rate` number: Optional. Employer matches this fraction of employee deferrals (e.g. 0.5).
    - `employer_match_cap_pct` number: Match applies up to this fraction of compensation (e.g. 0.06).
  - `result` object
    - `elective_deferral_limit` number: §402(g) base, before catch-up.
    - `catch_up_amount` number: Age-appropriate 401(k)-type catch-up.
    - `catch_up_type` 'none' | 'standard' | 'super_60_63'
    - `employee_deferral_max` number: Elective + catch-up, capped at compensation.
    - `dc_annual_additions_limit` number: §415(c): employee + employer, excl. catch-up (capped at compensation).
    - `ira_limit` number: Incl. age-50 catch-up, capped at compensation.
    - `simple_deferral_limit` number: Incl. applicable SIMPLE catch-up, capped at compensation.
    - `sep_max` number: min(25% of compensation, §415(c)).
    - `sep_eligible` boolean
    - `hsa_limit` number: Incl. 55+ catch-up; 0 if no coverage.
    - `catch_up_must_be_roth` boolean: SECURE 2.0 §603 (2026+).
    - `elective_deferral_headroom` number: Limit − YTD (floored at 0).
    - `ira_headroom` number
    - `hsa_headroom` number
    - `contribution_for_full_match` number: Employee deferral needed to capture the full employer match.
    - `employer_match_max` number: Matched dollars at that contribution.
    - `total_tax_advantaged_capacity` number: Employee deferral + match + IRA + HSA.
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)