# Códigos de error

> Los estados HTTP y los códigos de error de la API de Transacciones, con los mensajes exactos y el formato de los errores en el envío por lotes.

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

## Códigos HTTP

| Código | Significado |
|---|---|
| 200 | Éxito (GET, PATCH, batch) |
| 201 | Transacción creada (POST individual) |
| 204 | Transacción eliminada (DELETE) |
| 401 | Credenciales ausentes o inválidas |
| 403 | Empresa bloqueada |
| 404 | Transacción o merchant no encontrado |
| 409 | Conflicto (duplicado o transacción inmutable) |
| 422 | Error de validación (campos inválidos) |
| 429 | Demasiadas solicitudes (límite: 100 por minuto por IP) |
| 500 | Error interno del servidor |

---

## Formato de las respuestas de error

Todas las respuestas de error siguen el mismo formato:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descripción del error"
  }
}
```

---

## Códigos de error posibles

### Autenticación

| Código | HTTP | Mensaje |
|---|---|---|
| `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` |

### Validación

| Código | HTTP | Mensaje |
|---|---|---|
| `VALIDATION_ERROR` | 422 | Mensaje del validador (ej.: `card_last4 must be exactly 4 digits`) |

### Transacciones

| Código | HTTP | Mensaje |
|---|---|---|
| `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 | Mensaje |
|---|---|---|
| `RATE_LIMIT_EXCEEDED` | 429 | `Rate limit exceeded, retry in X seconds` |

---

## Errores en el envío por lotes

En el endpoint de batch, los errores individuales se devuelven en el array `errors` dentro de `data`, sin interrumpir el procesamiento de las demás transacciones:

```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 error incluye:
- `external_id`: identifica qué transacción falló.
- `status`: código HTTP equivalente del error.
- `error`: mensaje descriptivo.