Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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:

  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.

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

¿Te ha resultado útil esta página?