Errors and rate limits

For AI agents: this page is also Markdown at /developers/errors-and-rate-limits.md. Every docs page is listed in /developers/llms.txt.

Status codes, the error body, and how the 30 requests per minute limit works.

Errors return JSON with a message and the same disclaimer and docs link as successes:

{
  "error": "Expense \"not-a-real-slug\" not found",
  "meta": {
    "disclaimer": "This information is for educational purposes only and does not constitute tax, legal, or financial advice. Consult a qualified professional for your specific situation.",
    "api_docs": "https://www.hsatrackr.com/api/v1"
  }
}

Status	When
`400`	A required parameter is missing, or a number is outside the range shown on the endpoint's page. The message names it.
`404`	The slug does not exist, or `/limits` has no data for that year. List endpoints return valid slugs.
`429`	Over 30 requests in a minute from one IP. This body is only `{ error }`.

Inputs that do not error

Some inputs are handled quietly instead of returning 400. Check for them on your side:

An unknown category, eligibility or search value returns an empty list.
A number that is not a number (contribution=abc) uses the default shown on the endpoint's page.
limit outside 1 to 100 is clamped. A negative offset becomes 0.
Unknown provider slugs in /providers/compare are listed in invalidSlugs; the call fails only when fewer than two are valid.
limits?year=abc returns every year, and eligible?limit=abc returns every match.
Form 8889 flags such as age55 are true only when set to true. Negative dollar amounts are not rejected.
A year with no IRS limits is a 404 on /limits but a 400 on /calculator/form-8889.

Rate limits

Each IP gets 30 requests per minute across all endpoints. Successful responses send RateLimit-Limit and RateLimit-Policy: 30;w=60. A 429 also sends X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After in seconds.

Responses are cacheable for a day (Cache-Control: public, max-age=86400), so cache on your side before you reach the limit. Need more? Email support@hsatrackr.com.