# Erros

O formato dos erros da API da SinapsePay, os códigos HTTP e os principais códigos de erro, com o que fazer em cada caso.

Todo erro tem o mesmo formato:

```json
{
  "code": "VALIDATION_ERROR",
  "message": "Verifique os campos destacados",
  "errors": { "pagador.documento": "CPF ou CNPJ inválido" },
  "requestId": "6f1c2c8e-..."
}
```

`errors` aparece nos erros de validação, por campo, com os nomes da API. Informe o `requestId` ao suporte.

## Códigos HTTP

| HTTP | Quer dizer |
|---|---|
| `400` | Pedido malformado (`INVALID_JSON`, `IDEMPOTENCY_KEY_REQUIRED`) |
| `401` | Chave ausente, inválida, vencida ou revogada (`API_KEY_INVALID`) |
| `403` | A chave não pode fazer isso (`MISSING_SCOPE`, `IP_NOT_ALLOWED`, `ORGANIZATION_NOT_APPROVED`) |
| `404` | Não encontrada (`CHARGE_NOT_FOUND`) |
| `409` | A situação não permite (veja abaixo) |
| `422` | Campo a corrigir (`VALIDATION_ERROR`, com `errors`) |
| `429` | Limite da chave atingido (`TOO_MANY_ATTEMPTS`); espere o `Retry-After` |
| `5xx` | Falha nossa: repita com a mesma `Idempotency-Key` |

## Códigos de situação (`409`)

| `code` | O que fazer |
|---|---|
| `CHARGE_NOT_OPEN` | A cobrança não está em aberto (já paga, cancelada...) |
| `CHARGE_NOT_PAID` | Devolução só de cobrança paga |
| `NOTHING_TO_REFUND` | Todo o valor já foi devolvido |
| `REFUND_EXPIRED` | Passou dos 90 dias do pagamento |
| `REFUND_NOT_PIX` | Devolução só existe para PIX |
| `EXTERNAL_ID_IN_USE` | Já existe cobrança com esse `idExterno` |
| `NO_INTEGRATION` / `INTEGRATION_INACTIVE` / `NO_ACTIVE_CREDENTIAL` | Configure a integração e a credencial no painel |
| `MODULE_INACTIVE` | O módulo de cobranças não está ativo na organização |