Skip to main content
Error format SPB returns errors as RFC 9457 problem details. The API reference declares the application/problem+json media type and the Detail schema for these responses.
Field definitions
  • type – A URI that identifies the error in the Lerian error catalog, built as https://errors.lerian.studio/v1/<code>. A response with no code carries the RFC default about:blank.
  • title – The HTTP status text, for example Unprocessable Entity.
  • status – The HTTP status code.
  • detail – A human-readable explanation of this occurrence. For most 5xx responses SPB replaces the text with internal error, so the internal cause stays out of the response. Branch on code instead.
  • code – The stable SPB error code, in the format SPB-NNNN. A request that the router refuses, or that fails request-schema validation, carries no code.
  • errors – An optional list of per-field validation details. Each entry carries a message and a location.
  • correlationId – The request-scoped correlation identifier, when SPB resolved one. Quote this value in a support request.
The HTTP status depends on the layer that refuses the request. A request that reaches the handler and then breaks a business rule answers with the status in the tables below. The idempotency layer runs before the handler. A request it refuses for a missing or malformed key answers 400 Bad Request. A replay of a key still in flight answers 409 Conflict. The detail column summarizes the text that SPB puts in the detail field. The exact wording depends on the call site, because a call site can add request-specific context to it.

​
Validation and input errors

The SPB-0xxx range covers a request that SPB read and then refused.

​
HTTP 422 Unprocessable Entity

​
HTTP 413 Request Entity Too Large

​
HTTP 404 Not Found

​
HTTP 409 Conflict

​
Authentication and authorization errors

The SPB-2xxx range covers a request whose credential is absent or unusable, and a request that asks for an action outside its permissions.

​
HTTP 401 Unauthorized

​
HTTP 403 Forbidden

​
Processing and state errors

The SPB-3xxx range covers a request that SPB accepted and then could not apply. Three of these codes describe a state conflict that you can act on, so they answer 409 rather than a 5xx.

​
HTTP 409 Conflict

​
HTTP 500 Internal Server Error

​
Rate limiting errors

The SPB-4xxx range covers a caller that exceeded its request budget.

​
HTTP 429 Too Many Requests

​
Fallback errors

The SPB-9xxx range covers a failure on the Lerian side or in a component that SPB depends on. Retry a request that answers 503 or 504. For the other codes, quote the correlationId in a support request.

​
HTTP 500 Internal Server Error

​
HTTP 503 Service Unavailable

​
HTTP 504 Gateway Timeout

​
Rejections from the BACEN network

An SPB-NNNN code describes a decision that Lerian SPB made. A message that SPB transmits can still fail at the STR, and that rejection carries BACEN’s own vocabulary rather than an SPB-NNNN code. GET /v1/str/reports/rejected lists the rejected messages for a date range. Each rejected item carries a rejectReason field when BACEN supplied one. The value is BACEN’s own error code for the rejection, projected without change. SPB reads it from the error-code field on the STR error return that BACEN sends back. Treat rejectReason as an open vocabulary. The set of values belongs to BACEN, and it grows with the STR catalogue. Pass the value through to your operator rather than matching it against a fixed list in your client. The settlement outcome travels separately, in the sitLancSTR field on an operation. SPB projects the STR settlement status verbatim into that field. The field stays empty until the STR settles the operation.