# Códigos de erro

> Os status HTTP e os códigos de erro da API de Transações, com as mensagens exatas e o formato dos erros no envio em lote.

Página: https://doc.rapidchargeback.com/canais/transactions/codigos-de-erro/

## Códigos HTTP

| Código | Significado |
|---|---|
| 200 | Sucesso (GET, PATCH, batch) |
| 201 | Transação criada (POST single) |
| 204 | Transação deletada (DELETE) |
| 401 | Credenciais ausentes ou inválidas |
| 403 | Empresa bloqueada |
| 404 | Transação ou merchant não encontrado |
| 409 | Conflito (duplicata ou transação imutável) |
| 422 | Erro de validação (campos inválidos) |
| 429 | Muitas requisições (limite: 100 por minuto por IP) |
| 500 | Erro interno do servidor |

---

## Formato das respostas de erro

Todas as respostas de erro seguem o mesmo formato:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descrição do erro"
  }
}
```

---

## Códigos de erro possíveis

### Autenticação

| Código | HTTP | Mensagem |
|---|---|---|
| `UNAUTHORIZED` | 401 | `Missing or invalid Authorization header` |
| `UNAUTHORIZED` | 401 | `Invalid Basic Auth format` |
| `UNAUTHORIZED` | 401 | `Missing client_id or client_secret` |
| `UNAUTHORIZED` | 401 | `Invalid credentials` |
| `COMPANY_BLOCKED` | 403 | `Company is blocked` |

### Validação

| Código | HTTP | Mensagem |
|---|---|---|
| `VALIDATION_ERROR` | 422 | Mensagem do validador (ex: `card_last4 must be exactly 4 digits`) |

### Transações

| Código | HTTP | Mensagem |
|---|---|---|
| `TRANSACTION_NOT_FOUND` | 404 | `Transaction not found` |
| `TRANSACTION_DUPLICATE` | 409 | `Transaction already exists` |
| `TRANSACTION_DUPLICATE` | 409 | `Another transaction with this external_source/external_id already exists` |
| `TRANSACTION_IMMUTABLE` | 409 | `Transaction cannot be modified: it has been used by a network event` |
| `MERCHANT_NOT_FOUND` | 404 | `Merchant not found` |

### Rate limit

| Código | HTTP | Mensagem |
|---|---|---|
| `RATE_LIMIT_EXCEEDED` | 429 | `Rate limit exceeded, retry in X seconds` |

---

## Erros no envio em lote

No endpoint de batch, erros individuais são retornados no array `errors` dentro de `data`, sem interromper o processamento das demais transações:

```json
{
  "data": {
    "created": 1,
    "failed": 2,
    "results": [
      { "external_id": "TXN-2026-001", "tx_id": "uuid-1", "warnings": [] }
    ],
    "errors": [
      { "index": 1, "external_id": "TXN-2026-002", "status": 409, "error": "Transaction already exists" },
      { "index": 2, "external_id": "TXN-2026-003", "status": 404, "error": "Merchant not found" }
    ]
  }
}
```

Cada erro inclui:
- `external_id`: identifica qual transação falhou.
- `status`: código HTTP equivalente do erro.
- `error`: mensagem descritiva.