Validar errores en pruebas de API con Cypress va más allá de revisar un status code. Aquí aprendes a verificar tanto el código de respuesta como el mensaje que devuelve el servidor, usando APIs reales como PokéAPI y Rick and Morty para cubrir distintos formatos de error.

Por qué validar el mensaje y no solo el status code en Cypress

Cuando construimos nuestra propia API, un recurso inexistente suele devolver un status code 404 con un objeto vacío. Pero en el mundo real, las APIs casi nunca se comportan así. PokéAPI, por ejemplo, devuelve la cadena Not Found cuando buscas un pokémon que no existe, mientras que la API de Rick and Morty te regresa un objeto JSON con una propiedad error y el detalle del problema.

Esta diferencia importa porque tu prueba puede pasar con un 404 aunque el error real sea otro. Si solo validas el código, te pierdes el contexto. Validar el mensaje hace que tu aserción sea mucho más certera.

¿Qué pasa si una API devuelve un status code de error en Cypress? Por defecto, Cypress falla la prueba automáticamente. Para evitarlo y poder hacer aserciones sobre la respuesta, debes pasar failOnStatusCode: false dentro del objeto de configuración del cy.request.

Cómo configurar cy.request para que no falle en errores HTTP

El primer paso es estructurar el archivo de prueba. Crea un archivo error.spec con un describe que agrupe el contexto y un it que describa la validación, por ejemplo: debe validar el status code fallido y el mensaje de error.

Dentro del it, en vez de pasar solo la URL como string a cy.request, pasas un objeto con dos propiedades clave:

• url: el endpoint al que apuntas, incluyendo un recurso inexistente para forzar el 404.
• failOnStatusCode: false: evita que Cypress marque la prueba como fallida cuando el servidor responde con un código distinto a 2xx.

Luego encadenas un .then((response) => { ... }) para acceder a la respuesta y empezar a validar.

Cómo validar el status code 404 con expect y toEqual

Dentro del .then, accedes a response.status y comparas contra el código esperado. Para PokéAPI, al consultar un recurso inexistente, la aserción queda así:

javascript expect(response.status).to.equal(404)

Esa línea confirma que el servidor identificó el recurso como no encontrado. Hasta aquí cubres la mitad del trabajo.

Cómo validar el cuerpo de la respuesta cuando es texto plano

PokéAPI devuelve la cadena Not Found con F mayúscula, no un objeto. Por eso la aserción se hace directamente sobre response.body:

javascript expect(response.body).to.equal('Not Found')

Fíjate en el detalle de la mayúscula. Si escribes not found en minúsculas, la prueba falla aunque el endpoint esté respondiendo correctamente.

Cómo validar errores cuando la API responde con un objeto JSON

La API de Rick and Morty maneja los errores de forma distinta. Cuando pides un personaje o ubicación que no existe, no devuelve texto plano, sino un objeto del tipo { "error": "Location not found" }. Aquí necesitas otra estrategia.

En lugar de comparar el body completo con toEqual, usas toHaveProperty, que verifica dos cosas a la vez: que exista la propiedad y que su valor coincida.

javascript expect(response.body).to.have.property('error', 'Location not found')

Con esa aserción, tu prueba confirma que el objeto trae la llave error y que el mensaje es exactamente el esperado. Si la API cambia el texto o renombra la propiedad, la prueba falla y te avisa.

¿Cuándo uso toEqual y cuándo toHaveProperty en Cypress? Usa toEqual cuando comparas valores primitivos como strings, números o el body completo. Usa toHaveProperty cuando necesitas verificar una llave específica dentro de un objeto y, opcionalmente, su valor.

Por qué unir status code y body hace tus pruebas más confiables

Validar solo el 404 te da una falsa sensación de seguridad. Imagina que el endpoint cambia y empieza a responder 404 por un problema de autenticación, no porque el recurso no exista. Tu prueba seguiría pasando, pero el comportamiento real cambió.

Al unir ambas aserciones consigues:

• Confirmar que el servidor reconoció el caso de error.
• Verificar que el mensaje corresponde al motivo correcto.
• Detectar regresiones cuando la API modifica sus contratos.

Esto es especialmente útil porque cada empresa define sus propias políticas: algunas devuelven el 404 sin cuerpo, otras un string, otras un objeto estructurado. Tus pruebas deben adaptarse al contrato real, no al ideal.

Cómo aplicar esta validación a tu propia API

Si tu API solo devuelve un objeto vacío con el 404, el reto está en decidir qué afirmar sobre el body. Puedes validar que sea un objeto vacío con expect(response.body).to.deep.equal({}) o asegurarte de que ciertas propiedades no existan. La idea es que tu aserción describa con precisión el contrato actual.

¿Cómo lo resolverías tú? Déjalo en los comentarios y comparemos enfoques. En la siguiente clase pasamos de peticiones GET a probar el resto de métodos HTTP.