Error Handling

Application error responses follow RFC 9457 — Problem Details for HTTP APIs and are served as application/problem+json. The body always contains status, title, and instance. detail and violations appear on specific variants below.

Validation errors (400)

Validation failures return a list of violations so you can highlight every problem at once. No detail on this variant.

{
  "status": 400,
  "title": "Bad Request",
  "instance": "/v1/parties",
  "violations": [
    { "field": "firstName",                "in": "body",   "message": "must not be blank" },
    { "field": "taxIdentifications[0].tin", "in": "body",  "message": "must be a valid TIN" },
    { "field": "Idempotency-Key",          "in": "header", "message": "must not be blank" }
  ]
}

A missing or malformed request body returns the simpler shape with a detail field and no violations:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "HTTP 400 Bad Request",
  "instance": "/v1/parties"
}

Resource not found (404)

The resource does not exist, or the path or identifier could not be parsed.

{
  "status": 404,
  "title": "Not Found",
  "detail": "Resource not found",
  "instance": "/v1/accounts/00000000-0000-0000-0000-000000000000"
}

Method not allowed (405)

The endpoint exists but does not accept the HTTP method used.

{
  "status": 405,
  "title": "Method Not Allowed",
  "detail": "HTTP 405 Method Not Allowed",
  "instance": "/v1/parties"
}

Content negotiation (406, 415)

The Accept or Content-Type header is incompatible with what the endpoint produces or consumes.

{
  "status": 406,
  "title": "Not Acceptable",
  "detail": "The accept header value did not match the value in @Produces",
  "instance": "/v1/parties/{id}"
}

{
  "status": 415,
  "title": "Unsupported Media Type",
  "detail": "The content-type header value did not match the value in @Consumes",
  "instance": "/v1/parties"
}

Server errors (500)

An unexpected condition prevented the request from completing. Reads can be retried freely; for state-changing requests, retries are safe only when the original request included an Idempotency-Key.

{
  "status": 500,
  "title": "Internal Server Error",
  "instance": "/v1/accounts"
}

Status code summary

Status	Meaning
`202`	Request accepted for asynchronous processing. Track outcome via `correlationId` and webhooks.
`400`	Validation failure (`violations` present) or malformed request body (`detail` present).
`401`	Missing or invalid bearer token.
`403`	IP not whitelisted, or the bearer token lacks the permission required for the operation.
`404`	Resource not found, unknown route, or path parameter could not be parsed.
`405`	HTTP method not supported on this endpoint.
`406`	The `Accept` header is incompatible with what the endpoint produces.
`415`	The `Content-Type` of the request body is incompatible with what the endpoint consumes.
`500`	Internal server error. Reads can be retried freely; state-changing requests are safe to retry only with the original `Idempotency-Key`.
`502` / `503`	Edge proxy error. Body and `Content-Type` are not guaranteed to follow RFC 9457 — do not parse.

Getting Started

Parties

Accounts

Account Statements

Payments

Transactions

Transaction Postings

Oversight

Webhooks

Validation errors (400)

Resource not found (404)

Method not allowed (405)

Content negotiation (406, 415)

Server errors (500)

Status code summary

​Validation errors (400)

​Resource not found (404)

​Method not allowed (405)

​Content negotiation (406, 415)

​Server errors (500)

​Status code summary

Validation errors (400)

Resource not found (404)

Method not allowed (405)

Content negotiation (406, 415)

Server errors (500)

Status code summary