Resumen

  • RFC 7807, de marzo de 2016, fijó formatos JSON y XML para describir errores HTTP. La URI type era ya el identificador principal del problema para un cliente.
  • RFC 9457, de julio de 2023, sustituyó al anterior y detalló el coste de las URI relativas o de cambiar una identidad cuando una API quiere hacerla consultable.
  • La lista oficial de IANA reserva un espacio para tipos comunes. about:blank declara que el problema no añade significado al código de estado.

El 403 sabe poco del negocio

El código HTTP comunica una clase de resultado a bibliotecas, proxies y otras piezas generales. Ese idioma compartido sirve para detener la petición, pero no para decidir si una tienda debe invitar al usuario a añadir crédito o pedirle que corrija un dato. RFC 7807 dio una salida a esa diferencia: mantener la semántica general del estado y describir en el cuerpo un problema específico de la aplicación.

Su ejemplo presenta una compra rechazada con 403, un tipo de saldo insuficiente, una explicación de la ocurrencia y campos adicionales para saldo y cuentas. El formato application/problem+json es común; las extensiones y el tipo particular pertenecen al problema definido por quien opera la API. También se definió una representación XML. La innovación no consistía en convertir cualquier mensaje de error en una orden automática. Consistía en ofrecer un lugar estable para que un programa reconociera la clase de fallo.

Ese lugar es type. El documento de 2016 obligaba al consumidor a usar la cadena URI como identificador principal. title resumía el problema para personas y podía localizarse. detail explicaba una ocurrencia y no debía analizarse como si fuera un protocolo oculto entre frases. Un cliente que busca una palabra española o inglesa en la descripción queda a merced del redactor. Uno que reconoce una URI depende de una promesa más explícita: que el operador conservará el significado de ese nombre.

instance apunta a una ocurrencia concreta. La misma falta de crédito puede afectar a dos operaciones con instancias distintas. La diferencia importa para los registros y la atención al cliente: el tipo dice qué clase de respuesta corresponde; la instancia ayuda a localizar qué compra falló. Reducir ambos campos a un solo “identificador de error” borra una división útil.

Una casilla en blanco con reglas

Si falta type, su valor supuesto es about:blank. El nombre resulta seco, y precisamente por eso funciona: indica que el error carece de semántica adicional respecto del estado HTTP. Un cuerpo JSON con ese tipo no convierte un 404 corriente en una categoría nueva. Para pedir a un cliente que haga algo más específico, la API tiene que publicar otra identidad.

El campo status del cuerpo tampoco reemplaza el estado de la respuesta HTTP. Es informativo. El emisor debe usar el mismo número en ambos lugares, mientras el software genérico seguirá leyendo el de la propia respuesta. La duplicación ayuda cuando se conserva el cuerpo fuera de su contexto, aunque también abre la posibilidad de discrepancia si interviene un intermediario. La autoridad del formato no consiste en desobedecer la capa que lo transporta.

El coste de mudar el domicilio

RFC 9457 mantuvo la arquitectura en 2023 y explicó con más dureza las consecuencias de elegir mal la URI. Una referencia relativa como example-problem puede resolverse de dos maneras según la URL de la respuesta. Esas dos rutas identifican problemas diferentes aunque el texto se parezca. Por eso el sucesor recomienda URI absolutas cuando sea posible.

También permite URI que no se pueden consultar. Si una API adopta una y después decide ofrecer documentación en una dirección HTTP, sustituirla crea una identidad nueva. Los clientes que conocían el nombre antiguo pueden dejar de reconocer el mismo fallo. Una decisión de nomenclatura tomada en una reunión de diseño termina imponiendo trabajo a quienes mantienen las versiones del cliente durante años.

La revisión aclara la respuesta a problemas simultáneos: un tipo de validación puede llevar una extensión con varios campos incorrectos; ante tipos distintos, conviene mostrar el más relevante o urgente. Una respuesta HTTP tiene un estado, y una bolsa indiscriminada de fallos no señala qué decisión debe prevalecer. El registro IANA ofrece tipos reutilizables de alcance general, bajo el requisito de una especificación. Los errores propios de una empresa permanecen bajo la autoridad de esa empresa.

Faltan capturas de respuestas fechadas y versiones de clientes para medir el despliegue histórico. Los textos normativos sí muestran el cambio de responsabilidades: el IETF definió el sobre; cada operador responde por la dirección y el sentido de los errores que pone dentro.