---
title: Idempotencia, ETags y errores
category:
  uri: guides
content:
  excerpt: Reintenta solicitudes de forma segura y responde correctamente a errores HTTP.
---

# Idempotencia, ETags y errores

## Idempotency-Key

Toda escritura financiera exige una clave estable de hasta 200 caracteres:

```http
Idempotency-Key: movement-workflow-1042-item-3
```

Reutiliza la misma clave al reintentar la misma intención. Una repetición válida devuelve el resultado original y establece `meta.idempotentReplay`. Cambiar la clave representa una operación distinta y puede crear un duplicado.

No reutilices una clave con un body diferente: la API responde con conflicto.

## ETags

La corrección de movimientos usa concurrencia optimista. Obtén el `ETag` con `GET /movements/{movementId}` y envíalo en `If-Match`. Si el movimiento cambió, vuelve a consultarlo antes de decidir cómo combinar la corrección.

## Envelope de error

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Solicitud invalida",
    "details": {}
  },
  "meta": {
    "apiVersion": "1",
    "requestId": "b04d4f0f-413f-4678-921a-2c7b45ed975e"
  }
}
```

| HTTP | Acción recomendada |
| --- | --- |
| `400` | Corrige JSON, parámetros o encabezados; no repitas la misma solicitud. |
| `401` | Renueva o reemplaza la credencial. |
| `403` | Revisa scopes, tracker y membresía. |
| `404` | Verifica el identificador y tracker efectivo. |
| `409` | Reconsulta el recurso o corrige el uso de idempotencia. |
| `429` | Respeta `Retry-After` y aplica backoff con jitter. |
| `500` | Realiza reintentos acotados y reporta `requestId`. |