# Versioning

> The Rais-Version header, what counts as a breaking change and how upgrades work.

Source: https://rais.app/docs/versioning

The Raïs API is versioned by date. The current version is **2026-10-26**.

## Where the version appears

- Every response, errors included, carries it in the `Rais-Version` header:

~~~http
HTTP/1.1 200 OK
Rais-Version: 2026-10-26
Rais-Request-Id: req_8f3a1c9d2b7e4a60
~~~

- Every [event](https://rais.app/docs/webhooks.md) carries it as `api_version`, which tells you what shape its payload has.
- The [OpenAPI document](/openapi.json) states it as `info.version`.

## Breaking and non-breaking changes

Changes that could break an integration will only ever come with a **new version**. They are announced in the [changelog](https://rais.app/docs/changelog.md) before they apply.

These changes are **not** breaking, and can happen within a version at any time:

- a new endpoint, a new optional request parameter, a new response field;
- a new value of an enumeration, for example a new event type or a new payment status;
- a new error code, or a new header;
- a change to the wording of an error `message`;
- longer ids, and a different order of the keys of an object.

These are breaking, and need a new version: removing or renaming a field, changing its type or its meaning, making an optional parameter required, and removing an endpoint or an event.

## Write tolerant code

- Ignore response fields you do not know.
- Do not fail on an event type, a status or an error code you do not know: handle the unknown value with a sensible default, and answer unknown events with a `2xx` status.
- Branch on error `code`, never on `message`.
- Do not depend on the order of the keys of a JSON object.

## Upgrading

When a new version is released, the changelog says what changes, why, and from when. Read it before you upgrade, test with sandbox keys, and watch the `Rais-Version` header of your responses in your logs.