Comprobar formato de clave de idempotencia

Verifica que la clave no esté vacía, que tenga la longitud suficiente para ser única en la práctica, que no supere una longitud máxima razonable y que cada carácter sea seguro en una URL, de modo que la clave sobreviva a cabeceras, registros y cadenas de consulta sin sorpresas de codificación. Usted envía una cadena y recibe un indicador valid claro, la longitud medida y una lista de problemas concretos cuando algo falla.

Por qué las claves de idempotencia necesitan una comprobación de formato

Las claves de idempotencia existen para que una petición reintentada —un pago enviado dos veces, un pedido creado tras un tiempo de espera— se procese una única vez. Pero la seguridad que prometen depende de que la propia clave esté bien formada. Una clave demasiado corta colisiona con la de otro cliente y desduplica en silencio dos operaciones distintas en una sola. Una clave con caracteres fuera del alfabeto seguro para URL se deforma en algún punto entre su cliente, un proxy, la cadena de registros y el servidor, de modo que el reintento llega con una cadena distinta de la original y se cobra dos veces. Una clave vacía es rechazada directamente por la mayoría de las API, a menudo con un error genérico que cuesta una tarde rastrear. Pasar la clave por esta comprobación de formato de clave de idempotencia en el borde de su sistema detecta los tres modos de fallo en tiempo de desarrollo, en una suite de pruebas o en una validación previa dentro de su propio servicio, en lugar de en un informe de conciliación semanas después.

Qué se valida exactamente

La comprobación aplica la guía de formato que los procesadores de pago y el middleware de desduplicación documentan con más frecuencia. Primero, la clave debe ser una cadena no vacía; una clave vacía es un error, no una advertencia, porque ningún servidor la aceptará. Segundo, la longitud: por defecto la clave debe tener al menos 16 caracteres, el suelo por debajo del cual la unicidad deja de ser plausible, y como máximo 255 caracteres, el techo que la mayoría de los almacenes aceptan; ambos límites son configurables en cada llamada. Tercero, el alfabeto: cada carácter debe pertenecer al conjunto no reservado de RFC 3986 —letras, dígitos, guion, punto, guion bajo y tilde—. Esos caracteres atraviesan cabeceras HTTP, segmentos de URL y transportadores de registros sin codificación, que es exactamente por donde viajan las claves de idempotencia. Cuando un carácter falla, la respuesta enumera cada carácter infractor distinto para que vea si alguien incrustó un espacio, una barra o un emoji, y la matriz issues nombra el problema de forma legible por máquina: too_short, too_long o unsafe_characters.

Dónde encaja la comprobación en su arquitectura

La mayoría de los equipos la integran en dos lugares. El primero es el cliente que genera las claves: justo después de construir una clave a partir de un UUID, una marca de tiempo y un id de usuario, valídela una vez y registre una advertencia si falla, para que un error del generador aparezca en staging y no en producción. El segundo son las pruebas de contrato: pase un lote de claves de cada integración que posea por el endpoint en CI, de modo que una actualización de librería que cambie el comportamiento de codificación haga fallar la compilación. El endpoint es determinista y sin estado —no se almacena nada, no se consulta ninguna lista de claves vistas y la misma entrada siempre produce la misma salida—, lo que significa que es seguro llamarlo con claves reales y lo bastante barato, a $0.002 por petición, para ejecutarlo en cada despliegue. La misma validación también se ejecuta gratis en su navegador en esta página, de modo que un desarrollador puede pegar una clave sospechosa durante un incidente y obtener la misma respuesta que daría la API.