# Errors

The contract is the same on every `/v03` endpoint, and on most of `/v04`: **one JSON error shape, a few HTTP statuses, and no stable machine-readable error codes.** Handle a failure by its HTTP status — never by parsing the message text.

Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

## The error body

A business or validation failure returns **HTTP 400** with two fields:

```json
{
  "error": "Y-tunnus on virheellinen",
  "messageHtml": "Y-tunnus 1234567-9 on virheellinen."
}
```

- `error` — a short title. Currently in Finnish and **not a stable identifier**: do not branch your code on its text.
- `messageHtml` — a longer message you can show to a back-office user (also currently in Finnish). Not for parsing.
- **Validation failures** prefix `error` with `VALIDATION` and add a `validation` object with field-level details. Its presence is the signal that the request failed validation.

## Statuses you will hit

| Status | When | What to do |
|---|---|---|
| `400` | Any business or validation failure | Read `error` / `validation`, fix the request. Retrying the same request does not change the result |
| `401` | Missing, invalid or expired token. The body is empty: the reason is in the `WWW-Authenticate` header, for example `Bearer error="invalid_token"` | Get a new token and retry **once** — see [Tokens](https://code.salaxy.com/security/rest-authentication.md#tokens) |
| `404` | The resource does not exist. Used sparingly: most "not allowed" or "not valid" cases are `400` | Check the id and the account you act as |
| `5xx` | An unexpected server error, or a failure caught before the normal handling — **without** a JSON body | Retry transient errors with exponential backoff. Do not assume a body is present |

**A missing role fails as a bare `5xx`.** In production, calling an endpoint your account lacks the role for — for example [partner-initiated account creation](https://code.salaxy.com/security/account-creation.md) without the trusted partner role — fails as a server error, not a structured 400.

## Problem details on new v04 endpoints [v04 beta]

New endpoints in [API v04](https://code.salaxy.com/reference/rest-api-v04.md) return errors as **problem details** ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), content type `application/problem+json`). The first are the payment channel configuration endpoints (`/v04/api/settings/payment-channels/…/config`, one path per channel).

```json
{
  "type": "https://code.salaxy.com/problems/validation-failed",
  "status": 422,
  "title": "The payment channel config is not valid.",
  "errors": { "debitAccount.iban": ["…"] }
}
```

- `type` — a stable URI. **Branch your code on `type`**, not on the text. The URI opens the page that explains the type: see [Problem types](https://code.salaxy.com/problems/index.md).
- `title` and `detail` — in the language of `Accept-Language` (`fi` or `en`, Finnish by default).
- `errors` — only for `validation-failed`: the messages per field, keyed by the field's path in the JSON.

| `type` (after `https://code.salaxy.com/problems/`) | Status |
|---|---|
| [`not-found`](https://code.salaxy.com/problems/not-found.md) | 404 |
| [`channel-not-available`](https://code.salaxy.com/problems/channel-not-available.md) | 409 |
| [`concurrent-change`](https://code.salaxy.com/problems/concurrent-change.md) | 409 |
| [`precondition-failed`](https://code.salaxy.com/problems/precondition-failed.md) | 412 |
| [`unsupported-media-type`](https://code.salaxy.com/problems/unsupported-media-type.md) | 415 |
| [`validation-failed`](https://code.salaxy.com/problems/validation-failed.md) | 422 |
| [`internal-error`](https://code.salaxy.com/problems/internal-error.md) | 500 |

These endpoints document their error responses in the OpenAPI document.

## What generated clients see

For `/v03`, the [OpenAPI document](https://code.salaxy.com/reference/rest-api.md) describes only the **success** response of each endpoint. Error responses are not in it, so a generated client has no typed error model: read the status and the JSON body directly.

## Retries

- `5xx` — safe to retry with backoff.
- `400` and other `4xx` — fix the request first.
- `401` — tokens last 48 hours and there are no refresh tokens: repeat the grant and retry once.
- **Rate limits:** there is no documented rate limit or `Retry-After` today, so no `429` handling to implement.
- Making a retried *create* safe: see [Retries and idempotency](https://code.salaxy.com/reference/idempotency.md).

## Errors of a single endpoint

The reason for a `400` is in the `error` title, which is not stable. So the most useful documentation for an endpoint is a table of its failures and their causes. [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md) has one; use it as the pattern for the endpoints you integrate.

## Checklist

- Your code branches on the HTTP status, never on the `error` text.
- A `401` triggers one new token and one retry — not a loop.
- A `5xx` without a body is handled.
- `messageHtml` is shown to a person when a `400` needs fixing by hand.
