← All documentation

Error catalogue

Every error uses the Berlin Group tppMessages envelope:

{
  "tppMessages": [
    { "category": "ERROR", "code": "CONSENT_EXPIRED", "text": "The consent has expired." }
  ]
}

code is stable and safe to branch on. text is a short sentence for a human and may change without notice — do not parse it.

path — which field was wrong

When a refusal is about a specific field in your request body, we name it:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "FORMAT_ERROR",
      "path": "creditorAccount.iban",
      "text": "creditorAccount.iban is not a valid IBAN."
    }
  ]
}

Dot-notated, matching the request body. code tells you what kind of problem it is; path tells you where. Between them a FORMAT_ERROR is actionable — you can highlight the offending field for your own user — without reading text, which you are told not to parse.

path is absent when no single field is at fault, and that absence is meaningful rather than an omission. A refusal that names no field is one you cannot fix by correcting a value: a compliance outcome, a header problem, a state conflict, or a PAYMENT_FAILED whose cause is deliberately not disclosed. Treat “no path” as “do not retry a variation of this request”.

Codes we emit

Refusals that are identical on purpose

Three pairs are byte-identical, and no amount of retrying will separate them:

1. An unknown consent id and another provider’s consent — both CONSENT_UNKNOWN.
2. An account outside the consent and an account belonging to someone else — both CONSENT_INVALID.
3. Every payment-initiation failure — insufficient funds, unknown debtor account, a creditor IBAN we cannot route to, a creditor account belonging to the debtor’s own customer, limit breach, compliance hold — all PAYMENT_FAILED with the same sentence.

Each pair would otherwise be an oracle: ask a question, learn a fact about a customer that no consent covers. Treat them as one condition.

Consents never return 404

403 CONSENT_UNKNOWN subsumes “not found” on every consent operation. An id that never existed and one belonging to another provider answer identically — which is the whole point, since a distinguishable 404 would let you enumerate which consent ids are real.

So the consent operations declare no 404 at all, and a 404 branch on them is dead code. The only 404 in this interface is RESOURCE_UNKNOWN on a payment or on the templated authorisation read, where the id is one you were given rather than one you could guess.

Distinguishing our failures from your refusals

A 4xx means the interface understood you and said no. A 5xx means we broke. Only 5xx counts against our published availability figures, and your alerting should draw the same line — a rise in CONSENT_EXPIRED is a renewal problem in your integration, not an outage in ours.

Do not require a 5xx to parse. The application emits the usual tppMessages envelope, but a failure above it — load balancer, TLS termination, a timeout that never reaches the application — produces whatever that layer emits, which may be HTML or empty. 502, 503 and 504 mean the same thing as 500 and are handled the same way. Branch on the status code.

Retry guidance