Menú

Validación en la API: dónde cortar los errores

Comprobar un número en el límite de la API obliga a decidir qué se valida en el cliente, qué se valida en el servidor y qué se delega a una consulta externa. El reparto correcto evita errores silenciosos y servicios frágiles.

Publicado el

  • API
  • errores
  • arquitectura

Cada vez que un número cruza el límite de un servicio hay una oportunidad de detener un dato mal formado y un riesgo de rechazar uno correcto. El problema no se resuelve eligiendo un único lugar donde comprobar, sino repartiendo las comprobaciones según lo que cada una sabe y lo que cuesta ejecutarla. Este artículo describe ese reparto, la clasificación de errores que necesita y las precauciones que exige delegar una parte de la comprobación a un sistema ajeno.

¿La validación va en el cliente o en el servidor?

En los dos, pero con responsabilidades distintas. El cliente comprueba para dar una respuesta inmediata: mientras alguien escribe, puede avisar de que falta un carácter o de que el control no cuadra, sin esperar a ninguna red. Esa inmediatez mejora mucho la experiencia y no sustituye a nada.

El servidor comprueba porque es el único que puede hacerlo con autoridad. La comprobación del cliente se ejecuta en un entorno que el usuario controla, de modo que puede alterarse, desactivarse o simplemente no ejecutarse. Cualquier regla que proteja la integridad de los datos tiene que aplicarse también del lado del servidor, y la del cliente queda como una comodidad, no como un control.

La formulación útil para el equipo es esta: el cliente ayuda, el servidor decide. Toda la discusión sobre dónde poner la comprobación se resuelve sola cuando se acepta ese reparto.

Qué comprobar y qué dejar pasar en el límite

No todo merece la misma severidad, y tratar cada anomalía como un rechazo total produce servicios rígidos que nadie quiere usar.

  • La forma sí se puede exigir. Una cadena con caracteres imposibles o con longitud incorrecta no debería entrar.
  • El control aritmético se puede exigir cuando el esquema lo publica y no hay ambigüedad sobre cuál aplicar.
  • La pertenencia a un registro no se puede exigir sin más, porque depende de terceros y de su disponibilidad.
  • La coincidencia con un titular es otra comprobación completamente distinta y no se deduce de ninguna de las anteriores.

Un límite razonable deja pasar lo que no se puede comprobar y rechaza lo que está demostrado que no encaja. La tentación contraria, rechazar todo lo dudoso, convierte la duda del sistema en un problema del usuario.

Clasificación de errores y posibilidad de reintento

La clasificación de errores es lo que permite que el cliente sepa qué hacer sin leer un texto largo. Agrupar los resultados en unas pocas familias resuelve la mayor parte de los casos.

  1. Error de forma: falta un carácter, sobra uno o hay un símbolo no admitido. Se corrige volviendo a escribir el número.
  2. Error de control: la forma encaja pero el dígito verificador no cuadra. Se corrige revisando el número original.
  3. Forma confirmada sin control: no hay error que señalar y conviene decirlo así, sin ambigüedad.
  4. Sin regla disponible: no hay esquema conocido para esa entrada; merece revisión, no rechazo.
  5. Fallo de la comprobación externa: no se pudo consultar la fuente. Es un problema de infraestructura, no del dato.

Las dos últimas familias son las que suelen faltar en los diseños apresurados y las que generan más incidencias. Un fallo de la consulta externa no debería presentarse al usuario como un número inválido, porque no lo es: es un servicio que no respondió.

La distinción también decide si tiene sentido reintentar. Un error de forma no mejora repitiendo la petición; un fallo de la comprobación externa, sí, siempre que el cliente espere un poco antes de volver a intentarlo.

¿Por qué un fallo de comprobación no equivale a que el número no exista?

Porque la comprobación mira la coherencia interna de la cadena y la consulta mira un registro, y son operaciones independientes. Un número puede estar bien formado y no existir, o existir y no superar una comprobación mal aplicada, por ejemplo si se le ha elegido el esquema equivocado.

Esta confusión aparece en el texto de los mensajes de error mucho más que en el código. Un mensaje que diga que la cuenta no existe porque el control no cuadra está afirmando algo que el sistema nunca comprobó, y esa afirmación puede acabar teniendo consecuencias legales o comerciales.

El vocabulario que conviene usar es el mismo que emplea el resto de la herramienta: válido, no válido, solo formato y sin regla. Cada uno describe exactamente lo comprobado y ninguno promete más.

Límites de peticiones, tiempos de espera y alternativas

Cuando una parte de la comprobación depende de un servicio externo, entran en juego tres problemas que no desaparecen por ignorarlos.

El primero son los límites de uso. Un servicio ajeno impone un máximo de consultas, y un pico de tráfico puede agotarlo. Si el flujo principal depende de esa consulta, el límite se convierte en una caída.

El segundo son los tiempos de espera. Una consulta externa puede tardar o no responder nunca, y el sistema tiene que decidir cuánto está dispuesto a esperar antes de seguir sin ella. Esa decisión pertenece al diseño, no al azar de la configuración por defecto.

El tercero es la alternativa. Si la consulta falla, hay que tener preparado qué se hace: continuar con la comprobación local y marcar el resultado como pendiente suele ser mejor que bloquear la operación completa. Guardar en una caché el resultado de consultas recientes reduce el número de llamadas y mejora la resistencia del conjunto.

La guía sobre validación por lotes describe cómo se combinan esos mismos problemas cuando el volumen es alto y el proceso se ejecuta sin nadie delante.

Para quien programa: contrato, versión y registro

Unas cuantas decisiones de contrato evitan la mayoría de los incidentes posteriores.

  • Devuelve un estado con nombre, no un valor booleano, y documenta cuántos estados existen.
  • Incluye el esquema aplicado en la respuesta, para que el cliente pueda explicarla sin adivinar.
  • Versiona las reglas y registra la versión usada en cada comprobación.
  • No cambies el significado de un estado existente; añade uno nuevo si hace falta.
  • Separa en el registro los rechazos por forma de los fallos de la consulta externa, porque se investigan de forma distinta.
  • Documenta qué comprobación es informativa y cuál es bloqueante, para que nadie las confunda al integrar.

Hay un caso que merece atención aparte: las entradas para las que no existe ningún esquema conocido. La guía sobre números sin dígito verificador explica por qué esa respuesta no es un error y cómo debe viajar hasta el usuario final sin perder su significado.

Siguientes pasos

Dibuja el recorrido de un número desde que se escribe hasta que se guarda y marca en qué punto se comprueba cada una de las cinco familias de error. Verás enseguida si alguna no tiene sitio.

Después, pasa varios ejemplos inventados por el validador de números y compara los estados que devuelve con los que ofrece tu propia interfaz. Las diferencias suelen señalar mensajes que prometen más de lo comprobado.

Nota sobre los ejemplos de este artículo: las cadenas mencionadas se usan solo para ilustrar el reparto de comprobaciones entre cliente, servidor y servicios externos; no provienen de ningún sistema real ni identifican a ninguna persona o entidad.

Seguir leyendo

Artículos sobre Validador de DNI