Errors

Every error response is an RFC 9457 problem detail — including validation failures. There is no second error shape to handle, and no endpoint that returns a bare string on failure.

{
  "type":       "https://.../problems/validation-failed",  // stable; clients match on this
  "title":      "Validation failed",
  "status":     422,
  "detail":     "The submitted answers do not satisfy the form in force.",
  "instance":   "/v1/customers",
  "request_id": "01J...",                                   // quote this to support
  "errors": [
    { "field": "answers.source_of_funds", "code": "required", "message": "..." }
  ]
}

Match on type, not on titlePermalink to this section

The type URI is a stable, machine-readable identifier and is part of the contract. Titles and details are human-readable and may be reworded. A client branching on the title string is a client that breaks on a copy edit.

The request idPermalink to this section

Every problem carries a request id that appears in the application logs and in the audit trail. Quoting it to support turns 'a call failed this morning' into a single record. Log it on the client side for any non-2xx.

Reading a refusalPermalink to this section

Several statuses on this API mean 'the platform declines to pretend', and are worth handling distinctly rather than as generic failures.

Report transport unavailable

Returned by the legacy submit operation. The report exists, is valid and is approved — but its schema is not confirmed authoritative, so the platform will not record it as filed. This is a conflict, not a server fault, and retrying will not clear it.

Provider not configured

An identity-verification or watchlist adapter was called and none is registered. It is explicitly not a pass and not a soft failure; a caller that treats it as either has defeated the point of the distinction.

Step-up required

The operation needs re-authentication now, not a session from earlier. The problem names the requirement so a client can prompt.

Approval required

The change was accepted as a proposal rather than applied. Someone other than the caller must approve it.