Error Catalog

All error codes returned by the JDay API, with their HTTP status codes and meanings.

All JDay error responses use a consistent envelope:

{
  "error": {
    "code": "invalid_country",
    "message": "Country code must be one of the supported ISO 3166-1 alpha-2 values."
  },
  "request_id": "018f7d1a-3a51-7f4b-9c78-830f8b6ce220"
}

Error Codes

HTTP	Code	Meaning
400	`missing_parameter`	Required query parameter missing.
400	`invalid_date`	Provided date is malformed or not `YYYY-MM-DD`.
400	`invalid_year`	Provided `year` is malformed or not in 2025–2027.
400	`invalid_days`	Provided `days` is malformed, non-integer, or outside signed 32-bit range.
400	`invalid_country`	Unsupported country code.
400	`invalid_region`	Region malformed, unsupported for country, or invalid code.
400	`date_out_of_range`	Input or computed result falls outside 2025-01-01 to 2027-12-31.
401	`unauthorized`	Missing, malformed, unknown, revoked, or invalid credentials.
403	`plan_upgrade_required`	Valid request requires a higher plan.
405	`method_not_allowed`	Unsupported HTTP method for endpoint.
429	`rate_limited`	Per-key rate limit exceeded.
429	`monthly_limit_reached`	Account monthly quota exhausted.
500	`internal_error`	Internal platform failure.

Missing vs Invalid Parameters

These rules are applied consistently across all endpoints:

missing_parameter — a required query parameter was not provided at all.
invalid_date — a date-like parameter was provided but is malformed or not YYYY-MM-DD.
invalid_year — year was provided but is malformed or outside 2025..2027.
invalid_days — days was provided but is malformed, has decimals, uses scientific notation, or exceeds signed 32-bit range.

Per-Endpoint Error Mapping

Endpoint	Missing params use	Invalid params use
`is-business-day`	`missing_parameter` (date, country)	`invalid_date`
`add-business-days`	`missing_parameter` (date, country, days)	`invalid_date`, `invalid_days`
`count-business-days`	`missing_parameter` (start, end, country)	`invalid_date`
`holidays`	`missing_parameter` (country, year)	`invalid_year`

Validation Order

The full validation order for authenticated endpoints:

Auth — verify API key → 401 unauthorized
Required params — check all present → 400 missing_parameter
Date/param parsing — validate format → 400 invalid_date, invalid_year, invalid_days
Date range — check supported range → 400 date_out_of_range
Country — validate country code → 400 invalid_country
Region — validate region support and code → 400 invalid_region
Entitlement — check plan allows request → 403 plan_upgrade_required
Quota — check monthly limit → 429 monthly_limit_reached

Special Response Headers

Error	Required Header
`401 unauthorized`	`WWW-Authenticate: Bearer realm="JDay"`
`405 method_not_allowed`	`Allow: GET`
`429 monthly_limit_reached`	`Retry-After` (delta-seconds until billing period ends)