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

# Lista de erros do SPB

> Consulte qualquer código de erro do SPB, o status HTTP que o responde e o vocabulário de rejeição que a rede do BACEN devolve.

**Formato de erro**

O SPB retorna erros como problem details da RFC 9457. A referência da API declara o media type `application/problem+json` e o schema `Detail` para essas respostas.

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

**Definições de campo**

* **`type`** – Um URI que identifica o erro no catálogo de erros da Lerian, construído como `https://errors.lerian.studio/v1/<code>`. Uma resposta sem `code` carrega o padrão da RFC `about:blank`.
* **`title`** – O texto do status HTTP, por exemplo `Unprocessable Entity`.
* **`status`** – O código de status HTTP.
* **`detail`** – Uma explicação legível dessa ocorrência. Para a maioria das respostas `5xx`, o SPB substitui o texto por `internal error`, então a causa interna fica fora da resposta. Decida com base em `code`.
* **`code`** – O código de erro estável do SPB, no formato `SPB-NNNN`. Uma requisição que o roteador recusa, ou que falha na validação de schema da requisição, não carrega `code`.
* **`errors`** – Uma lista opcional de detalhes de validação por campo. Cada entrada carrega um `message` e uma `location`.
* **`correlationId`** – O identificador de correlação da requisição, quando o SPB resolve um. Cite esse valor em uma solicitação de suporte.

O status HTTP depende da camada que recusa a requisição. Uma requisição que chega ao handler e então quebra uma regra de negócio responde com o status das tabelas abaixo. A camada de idempotência roda antes do handler. Uma requisição que ela recusa por uma chave ausente ou malformada responde `400 Bad Request`. Uma repetição de uma chave ainda em andamento responde `409 Conflict`.

A coluna `detail` resume o texto que o SPB coloca no campo `detail`. A formulação exata depende do ponto de chamada, porque um ponto de chamada pode adicionar contexto específico da requisição a ele.

## Erros de validação e entrada

***

A faixa `SPB-0xxx` cobre uma requisição que o SPB leu e então recusou.

### HTTP 422 Unprocessable Entity

| `code`   | Descrição                               | `detail`             |
| -------- | --------------------------------------- | -------------------- |
| SPB-0001 | Entrada obrigatória ausente ou inválida | invalid input        |
| SPB-0002 | Formato de campo inválido               | invalid field format |
| SPB-0003 | Falha na validação de regra de negócio  | validation failed    |

### HTTP 413 Request Entity Too Large

| `code`   | Descrição                                          | `detail`          |
| -------- | -------------------------------------------------- | ----------------- |
| SPB-0004 | Corpo da requisição maior que o limite configurado | payload too large |

### HTTP 404 Not Found

| `code`   | Descrição              | `detail`           |
| -------- | ---------------------- | ------------------ |
| SPB-0010 | Recurso não encontrado | resource not found |

### HTTP 409 Conflict

| `code`   | Descrição                                                                                                                          | `detail`                           |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| SPB-0011 | Recurso duplicado. Uma repetição que chega enquanto a requisição original ainda está em andamento também responde com esse código. | request is already being processed |

## Erros de autenticação e autorização

***

A faixa `SPB-2xxx` cobre uma requisição cuja credencial está ausente ou inutilizável, e uma requisição que pede uma ação fora de suas permissões.

### HTTP 401 Unauthorized

| `code`   | Descrição                | `detail`                |
| -------- | ------------------------ | ----------------------- |
| SPB-2001 | Autenticação obrigatória | authentication required |

### HTTP 403 Forbidden

| `code`   | Descrição                                                    | `detail`       |
| -------- | ------------------------------------------------------------ | -------------- |
| SPB-2002 | O solicitante não está autorizado para a ação                | not authorized |
| SPB-2003 | A requisição usou HTTP em texto puro onde o deploy exige TLS | HTTPS required |

## Erros de processamento e estado

***

A faixa `SPB-3xxx` cobre uma requisição que o SPB aceitou e depois não conseguiu aplicar. Três desses códigos descrevem um conflito de estado sobre o qual você pode agir, então respondem `409` em vez de um `5xx`.

### HTTP 409 Conflict

| `code`   | Descrição                                                           | `detail`                                            |
| -------- | ------------------------------------------------------------------- | --------------------------------------------------- |
| SPB-3004 | A prontidão do serviço bloqueia o comando                           | service is not ready for the requested operation    |
| SPB-3006 | O estado do ciclo de vida da operação não permite a ação solicitada | operation state does not allow the requested action |
| SPB-3007 | A nova tentativa solicitada conflita com o estado atual do recurso  | retry conflicts with current resource state         |

### HTTP 500 Internal Server Error

| `code`   | Descrição             | `detail`       |
| -------- | --------------------- | -------------- |
| SPB-3001 | Falha de persistência | internal error |

## Erros de limitação de taxa

***

A faixa `SPB-4xxx` cobre um solicitante que excedeu seu orçamento de requisições.

### HTTP 429 Too Many Requests

| `code`   | Descrição                                                              | `detail`            |
| -------- | ---------------------------------------------------------------------- | ------------------- |
| SPB-4001 | Limite de taxa excedido. Tente novamente após um intervalo de backoff. | rate limit exceeded |

## Erros de fallback

***

A faixa `SPB-9xxx` cobre uma falha do lado da Lerian ou em um componente do qual o SPB depende. Tente novamente uma requisição que responde `503` ou `504`. Para os demais códigos, cite o `correlationId` em uma solicitação de suporte.

### HTTP 500 Internal Server Error

| `code`   | Descrição                           | `detail`       |
| -------- | ----------------------------------- | -------------- |
| SPB-9000 | Erro interno inesperado do servidor | internal error |
| SPB-9003 | Falha no pipeline de mensagens      | internal error |

### HTTP 503 Service Unavailable

| `code`   | Descrição                                    | `detail`       |
| -------- | -------------------------------------------- | -------------- |
| SPB-9001 | Uma dependência downstream está indisponível | internal error |

### HTTP 504 Gateway Timeout

| `code`   | Descrição                         | `detail`       |
| -------- | --------------------------------- | -------------- |
| SPB-9002 | A operação atingiu o tempo limite | internal error |

## Rejeições da rede do BACEN

***

Um código `SPB-NNNN` descreve uma decisão que o Lerian SPB tomou. Uma mensagem que o SPB transmite ainda pode falhar no STR, e essa rejeição carrega o vocabulário próprio do BACEN em vez de um código `SPB-NNNN`.

`GET /v1/str/reports/rejected` lista as mensagens rejeitadas de um intervalo de datas. Cada item rejeitado carrega um campo `rejectReason` quando o BACEN fornece um. O valor é o próprio código de erro do BACEN para a rejeição, projetado sem alteração. O SPB o lê do campo de código de erro no retorno de erro do STR que o BACEN devolve.

Trate `rejectReason` como um vocabulário aberto. O conjunto de valores pertence ao BACEN, e cresce com o catálogo do STR. Repasse o valor ao seu operador em vez de compará-lo com uma lista fixa no seu cliente.

O resultado da liquidação viaja separadamente, no campo `sitLancSTR` de uma operação. O SPB projeta o status de liquidação do STR literalmente nesse campo. O campo permanece vazio até o STR liquidar a operação.