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

# Erros

> Todo erro da API segue o mesmo formato — e cada um diz o que fazer.

Toda resposta de erro (4xx/5xx) segue o [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) — mesmo shape, sempre:

```json theme={"system"}
{
  "type": "ERR_INTEGRATION_006",
  "title": "Método não disponível",
  "status": 422,
  "detail": "O método de pagamento informado não está habilitado no projeto.",
  "instance": "/api/v1/transactions"
}
```

| Campo                | O que é                                                                             |
| -------------------- | ----------------------------------------------------------------------------------- |
| `type` / `errorCode` | Código **estável** do erro — use ele no seu código, não a mensagem                  |
| `title`              | Título curto legível                                                                |
| `status`             | HTTP status (repetido no corpo)                                                     |
| `detail`             | Explicação do que aconteceu                                                         |
| `instance`           | Path da requisição que falhou                                                       |
| `details`            | Extras quando existem — ex.: `issues` com os campos inválidos em erros de validação |

<Tip>
  Trate erros pelo `status` + `type`. As mensagens (`title`/`detail`) podem melhorar com o tempo; os códigos não mudam.
</Tip>

## O que fazer com cada status

| Status | Significado                                                     | O que fazer                                                                                                                                                                              |
| ------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Payload inválido (validação)                                    | **Não repita** sem corrigir. Veja `details.issues` — lista campo a campo o que falhou.                                                                                                   |
| `401`  | API key ausente, inválida ou revogada                           | Confira o header `Authorization: Bearer sk_...` e se a chave não foi revogada no Dashboard.                                                                                              |
| `403`  | Autenticado, mas sem permissão                                  | Cheque o tipo de chave e o modo do projeto (projeto em sandbox bloqueia `sk_live_`).                                                                                                     |
| `404`  | Recurso não encontrado                                          | ID errado ou de outro projeto — a API não revela recursos de terceiros.                                                                                                                  |
| `409`  | `Idempotency-Key` em processamento                              | Outra requisição com a mesma chave está em voo. Aguarde \~1s e repita **com a mesma chave** — você recebe o replay. Veja [Idempotência](/pages/idempotency).                             |
| `422`  | Erro semântico                                                  | O payload é válido, mas algo do negócio impede: método não disponível, valor acima do limite do projeto, chave idempotente reusada com body diferente. Corrija a causa antes de repetir. |
| `429`  | Rate limit                                                      | Aguarde o header `Retry-After` (segundos) antes de repetir. Backoff exponencial se persistir.                                                                                            |
| `500`  | Erro interno                                                    | Repita com backoff. Se persistir, fale com o suporte informando o `instance` e o horário.                                                                                                |
| `503`  | Processamento temporariamente indisponível ou sistema sob carga | Transitório — repita com backoff. Na criação de transação, use [Idempotency-Key](/pages/idempotency) para repetir sem risco de duplicar.                                                 |

## Códigos que você vai encontrar

| `type`                | Status | Quando acontece                                               |
| --------------------- | ------ | ------------------------------------------------------------- |
| `ERR_VALIDATION_001`  | 400    | Campos inválidos no body/query (detalhes em `details.issues`) |
| `ERR_AUTH_009`        | 401    | API key inválida ou expirada                                  |
| `ERR_AUTHZ_001`       | 403    | Chave sem a permissão necessária para o recurso               |
| `ERR_TRANSACTION_001` | 404    | Transação não encontrada                                      |
| `ERR_INTEGRATION_006` | 422    | Método de pagamento não disponível no projeto                 |

## Caso especial: HTTP 202 na criação

`202` **não é erro** — é sucesso parcial. O PIX foi gerado, mas a persistência ficou pendente de reconciliação automática:

* `data.id` vem `null`; use `data.externalId` como referência
* O `pixCode` é **válido e pagável** — entregue ao comprador normalmente
* A transação aparece na listagem em alguns minutos, após a reconciliação

## Timeouts

A criação de transação pode levar até **30 segundos** no pior caso. Configure o timeout do seu cliente HTTP acima disso (o [SDK](/pages/sdk/node) usa 35s) e, ao repetir após timeout, **use a mesma `Idempotency-Key`** — se a criação tiver concluído, você recebe o replay em vez de um pagamento duplicado.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Idempotência" icon="rotate" href="/pages/idempotency">
    Reenvie criações com segurança depois de um timeout.
  </Card>

  <Card title="Configurar webhooks" icon="webhook" href="/pages/webhooks">
    Trate o resultado do pagamento de forma assíncrona.
  </Card>
</CardGroup>