Errores 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.
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.