Errores e idempotencia
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
Léalo junto con el resumen de la descripción general, Autenticación para casos 401 y Recetas 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:
{
"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.
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
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.
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 |
GET /api/v4/users/usr_123 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
La respuesta incluye:
ETag: "abc123version"
Luego:
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
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:
429— espereRetry-Aftersegundos (o el retraso sugerido que parsee su cliente), luego reintente la misma solicitud.- Fallos de red transitorios en lecturas seguras — reintente con retroceso exponencial y jitter.
- Fallos transitorios en creaciones — reintente con la misma
Idempotency-Key. 412en escrituras — no reintente a ciegas el mismo cuerpo con el ETag antiguo; vuelva a leer, concilie, envíe unIf-Matchnuevo.422/401/ la mayoría de400— corrija la solicitud; los reintentos sin cambios seguirán fallando.
Buenas prácticas
- Ramifique por
codede nivel superior, no solo por el texto legibletitle. - Exponga
meta.requestIdde llamadas exitosas y cualquier identificador devuelto en documentos de problema al registrar fallos. - Envíe siempre
Idempotency-Keydesde trabajos de creación automatizados. - Envíe siempre
If-Matchen escrituras de un solo recurso que lo requieran. - Mapee
404a una única ruta de «no disponible» en la interfaz o la lógica de sincronización; no trate de forma especial un403ficticio.
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.