Cómo validar datos de una API con Pydantic en Python

João Barros 05 de July de 2026 4 min de lectura

Cuando consumes una API REST en Python, nunca tienes la garantía de que los datos lleguen en el formato esperado: un campo puede venir como null, un número puede llegar como texto y, de repente, tu pipeline se rompe a mitad del procesamiento. Validar datos de una API con Pydantic resuelve exactamente esto: defines un modelo con los tipos que esperas y Pydantic comprueba, convierte y señala todo por ti, con mensajes de error claros cuando algo no encaja. El resultado es un código más robusto y menos horas perdidas cazando bugs provocados por datos inesperados.

Requisitos previos

Python 3.9 o superior instalado.
Conocimientos básicos de diccionarios y de la biblioteca requests.
Pydantic v2 instalado con pip install pydantic requests.
Una API REST que devuelva JSON (aquí usamos una pública de ejemplo).

Paso 1: Definir el modelo de datos

El primer paso para validar datos de una API es describir la forma que esperas recibir. En un modelo Pydantic, cada campo tiene un nombre y un tipo; si los datos no coinciden, la biblioteca lanza un error en lugar de dejar pasar valores inválidos. Este enfoque sustituye el acceso frágil a diccionarios (por ejemplo, dados['id']), que falla en silencio o revienta con un KeyError cuando la estructura cambia.

from pydantic import BaseModel

class Utilizador(BaseModel):
    id: int
    name: str
    email: str
    ativo: bool = True

El campo ativo tiene un valor por defecto (True), por lo que es opcional: si la API no lo envía, el modelo asume ese valor automáticamente. Los demás campos son obligatorios. Definir tipos explícitos también sirve como documentación viva: cualquiera que lea el modelo entiende de inmediato qué devuelve la API.

Paso 2: Validar un único registro

Con el modelo listo, valida un diccionario con el método model_validate(). Un detalle útil: Pydantic convierte automáticamente los tipos compatibles, así que la cadena "42" se convierte en el entero 42 sin esfuerzo por tu parte. Si prefieres impedir estas conversiones automáticas y exigir tipos exactos, Pydantic también admite el modo estricto, pero para datos que vienen de JSON la conversión flexible suele ser lo que quieres.

dados = {"id": "42", "name": "Ana", "email": "ana@exemplo.pt"}

utilizador = Utilizador.model_validate(dados)
print(utilizador.id)      # 42 (int, convertido de texto)
print(utilizador.ativo)   # True (valor por omissão)

Paso 3: Capturar errores de validación

Cuando falta un campo obligatorio o tiene el tipo equivocado, Pydantic lanza la excepción ValidationError con una descripción detallada. Envuelve la validación en un try/except para tratar el problema sin interrumpir el programa.

from pydantic import ValidationError

mau = {"id": "abc", "name": "Rui"}  # id não numérico e email em falta

try:
    Utilizador.model_validate(mau)
except ValidationError as erro:
    print(erro)

El mensaje indica exactamente qué campo es problemático y por qué. Esto hace que la depuración sea mucho más rápida que descubrir el error tres pasos más adelante, ya dentro del pipeline.

Consejo: valida los datos justo en la entrada, en cuanto recibes la respuesta de la API. Cuanto antes detectas un error, más barato es corregirlo.

Paso 4: Validar una lista de registros

En la práctica, una API casi siempre devuelve una lista de objetos. Para validarlos todos de una vez sin escribir un bucle a mano, usa TypeAdapter con el tipo list[Utilizador]. Así, con una sola línea, garantizas que todos los registros respetan el contrato definido en el modelo.

import requests
from pydantic import TypeAdapter

resposta = requests.get("https://jsonplaceholder.typicode.com/users")
resposta.raise_for_status()

validador = TypeAdapter(list[Utilizador])
utilizadores = validador.validate_python(resposta.json())

print(f"{len(utilizadores)} utilizadores validados")

Los campos adicionales que la API envía y que no están en el modelo (como phone o address) simplemente se ignoran, dejando tu objeto limpio y predecible.

Verificar el resultado

Haz dos comprobaciones rápidas para confirmar que la validación funciona. Primero, con datos correctos, accede a un atributo y confirma el tipo: por ejemplo, utilizadores[0].id debe devolver un entero. Segundo, fuerza un error a propósito: cambia un id por texto no numérico y confirma que se lanza el ValidationError. Si ambos comportamientos ocurren, tu capa de validación está lista para proteger el pipeline.

Conclusión

En cuatro pasos has aprendido a validar datos de una API con Pydantic: definir el modelo, validar un registro, capturar errores y validar listas enteras. A partir de aquí puedes avanzar hacia validaciones personalizadas con field_validator, campos opcionales más ricos y la generación automática de JSON Schema a partir del modelo. ¿Qué campo de tu API necesita más una regla de validación a medida?