Skip to content

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 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 ​

StatusWhenWhat to do
400Any business or validation failureRead error / validation, fix the request. Retrying the same request does not change the result
401Missing, 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
404The resource does not exist. Used sparingly: most "not allowed" or "not valid" cases are 400Check the id and the account you act as
5xxAn unexpected server error, or a failure caught before the normal handling — without a JSON bodyRetry 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 on type, not on the text. The URI opens the page that explains the type: see Problem types.
  • 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-found404
channel-not-available409
concurrent-change409
precondition-failed412
unsupported-media-type415
validation-failed422
internal-error500

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.
  • 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.

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 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.

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.