Appearance
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 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
errorwithVALIDATIONand add avalidationobject 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 |
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 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 return errors as problem details (RFC 9457, 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 ontype, not on the text. The URI opens the page that explains the type: see Problem types.titleanddetail— in the language ofAccept-Language(fioren, Finnish by default).errors— only forvalidation-failed: the messages per field, keyed by the field's path in the JSON.
type (after https://code.salaxy.com/problems/) | Status |
|---|---|
not-found | 404 |
channel-not-available | 409 |
concurrent-change | 409 |
precondition-failed | 412 |
unsupported-media-type | 415 |
validation-failed | 422 |
internal-error | 500 |
These endpoints document their error responses in the OpenAPI document.
What generated clients see
For /v03, the OpenAPI document 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.400and other4xx— 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-Aftertoday, so no429handling to implement. - Making a retried create safe: see Retries and idempotency.
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 has one; use it as the pattern for the endpoints you integrate.
Checklist
- Your code branches on the HTTP status, never on the
errortext. - A
401triggers one new token and one retry — not a loop. - A
5xxwithout a body is handled. messageHtmlis shown to a person when a400needs fixing by hand.

