Errores, reintentos e idempotencia

Una integración fiable distingue entre una petición inválida, una falta de permiso y un fallo temporal. El código HTTP debe guiar la siguiente acción.

Códigos frecuentes

Código	Significado	Qué hacer
400	Petición mal formada	Corrige el JSON, parámetros o cabeceras.
401	Credencial ausente o inválida	Revisa, rota o vuelve a configurar la clave.
403	Scope o acceso insuficiente	Solicita solo el permiso necesario.
404	Recurso o capacidad no disponible	Comprueba el identificador y las capacidades.
409	Conflicto o duplicado	Relee el recurso y aplica una decisión explícita.
422	Datos no válidos	Muestra los campos que deben corregirse.
429	Límite temporal	Espera y reintenta con backoff.
5xx	Error temporal del servicio	Reintenta de forma limitada y registra el request_id.

Idempotencia

En mutaciones usa una clave estable en Idempotency-Key. Si la red falla después de enviar una operación, puedes repetir la misma petición sin crear duplicados. No reutilices la clave para operaciones diferentes.

Reintentos

Reintenta solo errores temporales y respeta el límite indicado por el servicio. Un backoff exponencial con jitter evita que todos los clientes vuelvan a intentarlo a la vez. Establece un máximo de intentos y una cola de revisión manual.

Paginación y búsqueda

Las listas pueden estar paginadas. Conserva el cursor o página que devuelva la respuesta y no asumas que el primer resultado es el único. Cuando sincronices cambios, guarda el identificador y el momento de la última lectura.

Observabilidad

Registra método, recurso, código, duración, número de intento y request_id. Redacta cuerpos que contengan datos personales y nunca registres claves, firmas o contraseñas.