> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# SPB error list

> Look up any SPB error code, the HTTP status that answers it, and the rejection vocabulary that the BACEN network sends back.

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

<CodeGroup>
  ```json JSON theme={null}
  {
    "type": "https://errors.lerian.studio/v1/SPB-0003",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "validation failed",
    "code": "SPB-0003",
    "correlationId": "req-7a3f9c2e"
  }
  ```
</CodeGroup>

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

| `code`   | Description                       | `detail`             |
| -------- | --------------------------------- | -------------------- |
| SPB-0001 | Missing or invalid required input | invalid input        |
| SPB-0002 | Invalid field format              | invalid field format |
| SPB-0003 | Business-rule validation failed   | validation failed    |

### HTTP 413 Request Entity Too Large

| `code`   | Description                                   | `detail`          |
| -------- | --------------------------------------------- | ----------------- |
| SPB-0004 | Request body larger than the configured limit | payload too large |

### HTTP 404 Not Found

| `code`   | Description        | `detail`           |
| -------- | ------------------ | ------------------ |
| SPB-0010 | Resource not found | resource not found |

### HTTP 409 Conflict

| `code`   | Description                                                                                                     | `detail`                           |
| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| SPB-0011 | Duplicate resource. A replay that arrives while the original request is still in flight also answers this code. | request is already being processed |

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

| `code`   | Description             | `detail`                |
| -------- | ----------------------- | ----------------------- |
| SPB-2001 | Authentication required | authentication required |

### HTTP 403 Forbidden

| `code`   | Description                                                       | `detail`       |
| -------- | ----------------------------------------------------------------- | -------------- |
| SPB-2002 | The caller is not authorized for the action                       | not authorized |
| SPB-2003 | The request used plaintext HTTP where the deployment requires TLS | HTTPS required |

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

| `code`   | Description                                                       | `detail`                                            |
| -------- | ----------------------------------------------------------------- | --------------------------------------------------- |
| SPB-3004 | Service readiness blocks the command                              | service is not ready for the requested operation    |
| SPB-3006 | The operation lifecycle state does not allow the requested action | operation state does not allow the requested action |
| SPB-3007 | The requested retry conflicts with the current resource state     | retry conflicts with current resource state         |

### HTTP 500 Internal Server Error

| `code`   | Description         | `detail`       |
| -------- | ------------------- | -------------- |
| SPB-3001 | Persistence failure | internal error |

## Rate limiting errors

***

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

### HTTP 429 Too Many Requests

| `code`   | Description                                          | `detail`            |
| -------- | ---------------------------------------------------- | ------------------- |
| SPB-4001 | Rate limit exceeded. Retry after a backoff interval. | rate limit exceeded |

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

| `code`   | Description                      | `detail`       |
| -------- | -------------------------------- | -------------- |
| SPB-9000 | Unexpected internal server error | internal error |
| SPB-9003 | Message pipeline failure         | internal error |

### HTTP 503 Service Unavailable

| `code`   | Description                            | `detail`       |
| -------- | -------------------------------------- | -------------- |
| SPB-9001 | A downstream dependency is unavailable | internal error |

### HTTP 504 Gateway Timeout

| `code`   | Description             | `detail`       |
| -------- | ----------------------- | -------------- |
| SPB-9002 | The operation timed out | internal error |

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