# Error codes

> The HTTP statuses and error codes of the Transactions API, with the exact messages and the error format in batch upload.

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

## HTTP codes

| Code | Meaning |
|---|---|
| 200 | Success (GET, PATCH, batch) |
| 201 | Transaction created (single POST) |
| 204 | Transaction deleted (DELETE) |
| 401 | Missing or invalid credentials |
| 403 | Company blocked |
| 404 | Transaction or merchant not found |
| 409 | Conflict (duplicate or immutable transaction) |
| 422 | Validation error (invalid fields) |
| 429 | Too many requests (limit: 100 per minute per IP) |
| 500 | Internal server error |

---

## Error response format

Every error response follows the same format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}
```

---

## Possible error codes

### Authentication

| Code | HTTP | Message |
|---|---|---|
| `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` |

### Validation

| Code | HTTP | Message |
|---|---|---|
| `VALIDATION_ERROR` | 422 | Validator message (e.g. `card_last4 must be exactly 4 digits`) |

### Transactions

| Code | HTTP | Message |
|---|---|---|
| `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

| Code | HTTP | Message |
|---|---|---|
| `RATE_LIMIT_EXCEEDED` | 429 | `Rate limit exceeded, retry in X seconds` |

---

## Errors in batch upload

On the batch endpoint, individual errors are returned in the `errors` array inside `data`, without stopping the processing of the other transactions:

```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" }
    ]
  }
}
```

Each error includes:
- `external_id`: identifies which transaction failed.
- `status`: the equivalent HTTP code of the error.
- `error`: descriptive message.