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

> Consulte os códigos de erro do Streaming Hub, o status HTTP que cada um carrega e o que corrigir na requisição que o gerou.

**Formato do erro**

O Streaming Hub retorna a maioria dos erros como problem details da RFC 9457, com o media type `application/problem+json`. Apenas uma resposta nesse media type carrega o envelope abaixo:

<CodeGroup>
  ```json JSON theme={null}
  {
    "type": "https://errors.lerian.studio/v1/not_found",
    "title": "Not Found",
    "status": 404,
    "detail": "subscription not found",
    "code": "not_found"
  }
  ```
</CodeGroup>

**Definições dos campos**

* **`type`** – Uma URI estável e versionada que identifica o tipo do problema. O Streaming Hub a monta como `https://errors.lerian.studio/v1/<code>` e a omite para um problema ao qual não atribui nenhum código.
* **`title`** – Um resumo curto e legível por humanos, que é o texto do status HTTP (por exemplo, `Not Found`).
* **`status`** – O código de status HTTP, espelhado no corpo.
* **`detail`** – Uma explicação segura para o chamador sobre essa ocorrência. Para uma resposta `5xx`, o Streaming Hub reduz o detail à string estática `internal error`, para que nenhuma causa interna vaze.
* **`code`** – O token estável, de baixa cardinalidade e legível por máquina para basear a ramificação. Uma falha de validação da requisição, e uma requisição que não corresponde a nenhuma rota, chegam com esse campo vazio. Baseie a ramificação em `status` nesse caso. Baseie a ramificação em `status` nesse caso.

## Erros do cliente

***

| `code`                            | Descrição                                                                                                                                                                            | Status |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| `bad_request`                     | A requisição está malformada, ou falta uma entrada obrigatória.                                                                                                                      | 400    |
| `missing_idempotency_key`         | A requisição omite o header obrigatório `X-Idempotency`. O Streaming Hub rejeita a requisição antes de qualquer escrita.                                                             | 400    |
| `invalid_error_class`             | O filtro `error_class` na listagem de dead-letter contém um valor fora das classes de transporte reconhecidas. Forneça uma classe reconhecida.                                       | 400    |
| `invalid_cursor`                  | O cursor `after` na listagem de dead-letter não é um identificador de linha bem formado. Reinicie a listagem.                                                                        | 400    |
| `unauthorized`                    | A autenticação falhou, ou a requisição não carrega um contexto de tenant confiável. O corpo é o mesmo para cada causa que o hub responde por conta própria.                          | 401    |
| `forbidden`                       | A credencial é válida, mas o escopo delegado que a requisição apresenta diverge da claim de escopo no token repassado.                                                               | 403    |
| `not_found`                       | O recurso está ausente, foi excluído de forma lógica, pertence a outro tenant ou é de outro tipo. O token é o mesmo para cada um desses casos.                                       | 404    |
| `idempotency_conflict`            | Uma requisição duplicada está em andamento, ou a mesma chave `X-Idempotency` chegou com uma fingerprint de requisição diferente.                                                     | 409    |
| `validation_error`                | A requisição carrega uma falha de formato corrigível pelo chamador: um `sink_kind` inválido, ou um endpoint, schema ou valor de `event_types` inválido.                              | 422    |
| `inline_sink_config_forbidden`    | Uma requisição de criação carregou material `sink_config` ou `credential` embutido. Em vez disso, envie a credencial da fila por `PUT /v1/subscriptions/{id}/credential`.            | 422    |
| `endpoint_blocked`                | O host resolvido está bloqueado, é privado ou é um endereço de metadados, ou a URL carrega informação de usuário embutida. Forneça um endpoint público que não contenha credenciais. | 422    |
| `no_secret_to_rotate`             | Uma rotação de secret teve como alvo uma subscription que não possui secret de assinatura.                                                                                           | 422    |
| `probe_unsupported_for_sink_kind` | O sink kind não tem nenhuma probe registrada para essa operação. Os sink kinds desse grupo verificam por suas próprias superfícies.                                                  | 422    |
| `rate_limited`                    | O throttle de leitura de entrada por tenant negou a requisição. Aguarde e tente novamente.                                                                                           | 429    |

<Note>
  A camada de autenticação e autorização executa antes do Streaming Hub. Um `401` ou um `403` recusado por essa camada retorna um corpo em texto simples, não um documento de problema. Esse corpo não carrega `code`.
</Note>

## Erros do servidor

***

| `code`           | Descrição                                                                                            | Status |
| ---------------- | ---------------------------------------------------------------------------------------------------- | ------ |
| `internal_error` | Uma falha de infraestrutura. O Streaming Hub reduz o `detail` a `internal error` e registra a causa. | 500    |