> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kash.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# API_VERSION_UNSUPPORTED

> HTTP 410 — API version unsupported

**HTTP status:** 410 · **Title:** "API version unsupported"

## When it fires

Your request sent an `X-Kash-Api-Version` header whose value is not in
`SUPPORTED_PUBLIC_API_VERSIONS`. The runtime accepts only
date-string values that the API has actively published as a supported
contract version. Unrecognized values — typos, future-dated guesses,
versions long past their sunset window — return this error.

## Why 410?

`410 Gone` is the right semantic: the version was either once
accepted (an old date past its 12-month deprecation window) or never
has been (a typo, a future date). Either way, sending the request
again with the same value will not succeed. `400` would imply the
client could fix syntax and retry without changing the value — which
is not the case here. `406 Not Acceptable` is closer but is reserved
for content-type negotiation.

## Why it happens

* **Typo in the pin** — sent `2026-04-30` when the canonical version
  is `2026-04-29`.
* **Pinned to a sunsetted version** — the date you pinned against
  passed its 12-month `Sunset` window and was removed from the
  supported set.
* **Pinned to a future version** — your client was upgraded with a
  version pin that the production API hasn't shipped yet (canary
  drift between client release and server deploy).
* **Multi-valued header confusion** — a load balancer or proxy
  appended a second `X-Kash-Api-Version` value (`,`-joined) and the
  runtime correctly refuses to silently pick one.

## How to recover

The response body's `metadata.supported` field carries the full list
of accepted versions, in canonical-default-first order:

```json theme={null}
{
  "type": "https://docs.kash.bot/developer-docs/api-errors/API_VERSION_UNSUPPORTED",
  "title": "API version unsupported",
  "status": 410,
  "code": "API_VERSION_UNSUPPORTED",
  "detail": "Requested API version '2099-01-01' is not supported. Send no header to use the current default (2026-04-29), or pick a value from the 'supported' list.",
  "instance": "/v1/markets",
  "requestId": "01HQGY8K2N3X4Z5C6D7E8F9G0H",
  "requested": "2099-01-01",
  "supported": ["2026-04-29"],
  "current": "2026-04-29"
}
```

Pick a value from `supported` and resend the request. The simplest
recovery is to **drop the header** entirely and let the runtime
default to `current` — that's the recommended consumer mode unless
you have a specific reason to pin.

## Migration policy

When the API ships a new version, the previous version stays in
`SUPPORTED_PUBLIC_API_VERSIONS` for **12 months** (per AD-15 / RFC
8594\). During that window, every response from the deprecated
version carries `Sunset: <date>` and `Deprecation: true` headers so
your monitoring can flag the impending expiry well before it hits.

If you're seeing this error on a date that is older than 12 months
since its `Sunset` was advertised, that's working as intended — it's
time to update the pin.

## Best practice

Don't pin if you don't have to. The default contract (no header)
runs against the current `PUBLIC_API_VERSION`, and we promise
additive, non-breaking changes within a date version. Pin only when
you're locking down a release for compliance or contract-test
reasons.

If you do pin, follow the registry: read
`https://api.kash.bot/v1/openapi.json` (or the live OpenAPI route)
and let your client library auto-select the highest version it
recognises.

## See also

* `apps/public-api/src/plugins/api-version.ts` — the negotiation
  plugin source.
* `packages/constants/src/public-api-version.ts` — the canonical
  registry.
* `apps/public-api/openapi/index.json` — the snapshot index, listing
  every published version.
* `docs/runbooks/hmac-algorithm-rotation.md` — example of a version
  bump driven by a security event.