---
icon: shield
title: Errores e idempotencia
description: Detalles de problemas RFC 7807, Idempotency-Key, concurrencia optimista ETag y límites de tasa para la API de Fuxam v4.
---

Cuando algo falla — o cuando reintenta a propósito — la API de Fuxam v4 sigue un conjunto pequeño de reglas estrictas: documentos de problema **RFC 7807** para errores, **`Idempotency-Key`** para creaciones seguras, **`ETag` / `If-Match`** para actualizaciones y eliminaciones seguras, y **`RateLimit-*` / `Retry-After`** cuando se supera el presupuesto compartido. Aprender esto una vez hace que cada endpoint sea más seguro de automatizar.

## Por qué importa

Las integraciones fallan en el mundo real: las redes se cortan a mitad de un POST, dos trabajos actualizan al mismo usuario, un bucle de sincronización supera las 1000 solicitudes por minuto. Sin idempotencia y controles de concurrencia se arriesga a registros duplicados o sobrescrituras silenciosas. Sin un `code` de error estable no puede ramificar de forma fiable en el código del cliente. Este capítulo es el contrato para esos modos de fallo.

## Cómo encaja

```mermaid
flowchart TD
  Request[Solicitud API] --> Ok{Exito}
  Ok -->|yes| Data[data y meta]
  Ok -->|no| Problem[problem mas json]
  Problem --> Code[code estable de nivel superior]
  Request --> Write{Escritura}
  Write -->|POST create| Idem[Idempotency-Key]
  Write -->|PATCH PUT DELETE| ETag[If-Match ETag]
```

Léalo junto con el resumen de la [descripción general](/docs/es/api/overview), [Autenticación](/docs/es/api/authentication) para casos `401` y [Recetas](/docs/es/api/recipes) para patrones listos para copiar.

## Conceptos clave

| Concepto | Significado |
|---|---|
| **Problem details** | Cuerpo JSON RFC 7807 con `Content-Type: application/problem+json`. |
| **ApiErrorCode** | Conjunto cerrado de valores `code` estables de nivel superior (por ejemplo `resource_not_found`). |
| **Zod issue code** | Códigos de validación por campo dentro de `errors[]` (por ejemplo `invalid_string`) con punteros RFC-6901. |
| **Idempotency-Key** | Clave generada por el cliente que hace que un `POST` de creación sea seguro ante reintentos dentro de la ventana de idempotencia. |
| **ETag / If-Match** | Concurrencia optimista: escribir solo si la versión del recurso sigue coincidiendo. |
| **Rate limit** | 1000 solicitudes/min por integración + institución (ventana deslizante). |

## Modelo de errores (RFC 7807)

Todos los errores usan `application/problem+json`. El campo `type` es la URI `https://fuxam.app/errors/{code}`.

Hay **dos espacios de nombres `code` distintos**:

| Espacio de nombres | Ubicación | Propósito |
|---|---|---|
| `code` de nivel superior | Raíz del documento de problema | Unión cerrada `ApiErrorCode` — legible por máquina y estable entre versiones de su cliente |
| `errors[].code` | Entradas opcionales del array | Códigos de incidencia Zod (por ejemplo `invalid_string`) con un `pointer` RFC-6901 (por ejemplo `/email`) |

Ejemplo:

```json
{
  "type": "https://fuxam.app/errors/resource_not_found",
  "title": "Not Found",
  "status": 404,
  "code": "resource_not_found"
}
```

### Sin 403 — privacidad por uniformidad

**v4 no emite `403`.** El acceso entre inquilinos devuelve el mismo `404 resource_not_found` que un recurso realmente inexistente. Nunca se filtra la existencia de identificadores de otra institución. El código del cliente debe tratar `404` como «no disponible para usted», no solo «nunca existió».

Los fallos de validación devuelven HTTP `422`.

## Códigos de estado habituales

| Estado | Significado típico |
|---|---|
| `200` | Lectura o actualización exitosa |
| `201` | Recurso creado |
| `204` | Recurso eliminado (sin cuerpo) |
| `400` | Solicitud incorrecta (por ejemplo `invalid_cursor`) |
| `401` | Autenticación fallida |
| `404` | Recurso inexistente **o** denegación entre inquilinos (`resource_not_found`) |
| `409` | Conflicto o bloqueo de idempotencia en curso |
| `412` | Desajuste de ETag (`precondition_failed`) |
| `422` | Fallo de validación |
| `428` | Falta `If-Match` requerido (`precondition_required`) |
| `429` | Límite de tasa superado — respete `Retry-After` |

## Idempotencia para creaciones

Las solicitudes POST que crean recursos aceptan un encabezado `Idempotency-Key`. Enviar la **misma clave** dos veces dentro de la ventana de idempotencia devuelve la **respuesta en caché** (incluido el `201` original) sin crear un duplicado. Claves en conflicto en curso pueden devolver `409`.

```http
POST /api/v4/users HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/json
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Accept: application/json
```

```bash
IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -d @create-body.json \
  "https://fuxam.app/api/v4/users"
```

Use el cuerpo JSON documentado en la referencia de la operación de creación; lo importante de este patrón es reutilizar la misma `Idempotency-Key` en los reintentos.

:::tip
Genere un UUID nuevo **por cada creación lógica**. Reutilice la misma clave solo al reintentar la **misma** creación prevista tras un fallo de red. No reutilice una clave para un payload distinto.
:::

## Concurrencia optimista (ETag)

Los `GET` de un solo recurso emiten un `ETag` fuerte. Envíelo de vuelta como `If-Match` en `PATCH`, `PUT` o `DELETE`:

| Resultado | Estado / código | Significado |
|---|---|---|
| Versión aún actual | Éxito (`200` / `204`) | Escritura aplicada |
| Recurso cambiado desde la lectura | `412` `precondition_failed` | Vuelva a hacer GET, fusione, reintente con nuevo ETag |
| `If-Match` requerido pero ausente | `428` `precondition_required` | Incluya `If-Match` |

```http
GET /api/v4/users/usr_123 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

La respuesta incluye:

```http
ETag: "abc123version"
```

Luego:

```http
PATCH /api/v4/users/usr_123 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/json
If-Match: "abc123version"
Accept: application/json
```

```bash
ETAG='"abc123version"'

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${ETAG}" \
  -d @patch-body.json \
  "https://fuxam.app/api/v4/users/usr_123"
```

Coloque en `patch-body.json` los campos que desee cambiar según la referencia del endpoint; empareje siempre la escritura con el `ETag` que acaba de leer.

## Límites de tasa

Cada integración comparte un presupuesto de **1000 solicitudes/min** (ventana deslizante, clave integración + institución). Las respuestas incluyen encabezados `RateLimit-*`. Al superar el presupuesto:

- Estado: `429`
- Encabezado: `Retry-After` (respételo antes de reintentar)

### Orientación sobre reintentos y retroceso

Trate los reintentos como una política en capas:

1. **`429`** — espere `Retry-After` segundos (o el retraso sugerido que parsee su cliente), luego reintente la misma solicitud.
2. **Fallos de red transitorios en lecturas seguras** — reintente con retroceso exponencial y jitter.
3. **Fallos transitorios en creaciones** — reintente con la **misma** `Idempotency-Key`.
4. **`412` en escrituras** — no reintente a ciegas el mismo cuerpo con el ETag antiguo; vuelva a leer, concilie, envíe un `If-Match` nuevo.
5. **`422` / `401` / la mayoría de `400`** — corrija la solicitud; los reintentos sin cambios seguirán fallando.

:::warning[Manténgase bajo el presupuesto]
Un bucle de paginación ajustado con `limit=1` puede agotar el presupuesto de 1000/min rápidamente. Prefiera páginas más grandes y retroceso cuando los encabezados `RateLimit-*` se acerquen a cero restantes.
:::

## Buenas prácticas

- Ramifique por `code` de nivel superior, no solo por el texto legible `title`.
- Exponga `meta.requestId` de llamadas exitosas y cualquier identificador devuelto en documentos de problema al registrar fallos.
- Envíe siempre `Idempotency-Key` desde trabajos de creación automatizados.
- Envíe siempre `If-Match` en escrituras de un solo recurso que lo requieran.
- Mapee `404` a una única ruta de «no disponible» en la interfaz o la lógica de sincronización; no trate de forma especial un `403` ficticio.

## Errores frecuentes

| Error | Consecuencia | Solución |
|---|---|---|
| Reintentar POST sin Idempotency-Key | Recursos duplicados | Genere y reutilice una clave por creación lógica |
| Ignorar 412 | Carreras de sobrescritura o reintentos infinitos | Vuelva a hacer GET y fusione |
| Tratar 404 siempre como «eliminar de caché local» | Puede ocultar permisos o inquilinos | Confirme primero con un id conocido válido |
| Bucle ocupado en 429 | Bloqueo más largo, cómputo desperdiciado | Respete `Retry-After` |

## Preguntas frecuentes

**¿Cuál es la diferencia entre los dos campos code?**

El `code` de nivel superior es la clasificación estable de error de la API. Las entradas en `errors[].code` describen incidencias de validación individuales (Zod) e incluyen un `pointer` al campo que falla.

**¿Veré alguna vez HTTP 403?**

No desde la ruta de denegación entre inquilinos de v4 — eso es intencionalmente `404`. Diseñe los clientes en consecuencia.

**¿Cuánto dura la ventana de idempotencia?**

La descripción general documenta que las repeticiones dentro de la ventana de idempotencia devuelven la respuesta en caché. Trate la clave como válida para periodos de reintento razonables; no confíe en las claves para siempre — use una clave nueva para cada creación lógica nueva.

## Páginas relacionadas

**[Recetas](/docs/es/api/recipes)**

Recorridos de actualización segura y creación idempotente.

**[Paginación y filtrado](/docs/es/api/pagination-and-filtering)**

invalid_cursor y recorridos eficientes de listas.

**[Autenticación](/docs/es/api/authentication)**

401 y manejo de credenciales.

**[Descripción general de la API](/docs/es/api/overview)**

Resumen de convenciones y notas de migración.
