Mensajes de error de API según RFC 9457 (Problem Details)

Qué es

RFC 9457 sustituye a RFC 7807 y describe un objeto JSON que un servidor envía con el tipo de medio application/problem+json (o application/problem+xml) como cuerpo de respuesta en caso de error. Los campos: type — una URI que identifica la clase de error y que, idealmente, ofrece una descripción al consultarla; si falta, se aplica about:blank. title — un resumen breve, igual para todas las apariciones de esa clase. status — el código de estado HTTP como número. detail — una explicación de esta aparición concreta. instance — una URI que designa esta aparición. Los campos de extensión propios («Extension Members») están expresamente previstos, por ejemplo una lista de errores de campo en una validación.

Por qué importa

El código de estado por sí solo es demasiado impreciso: dos respuestas 409 pueden significar «versión desactualizada» y «nombre ya utilizado», y exigen reacciones distintas. Un cliente que puede bifurcar según type decide entre reintentar, recargar o desistir sin analizar un texto de mensaje que cambiará con la siguiente versión. Para los agentes que usan las API a partir de la documentación, un catálogo de errores estable y documentado es el requisito para no tener que adivinar.

Cómo aplicarlo

• Un formato de error para todas las respuestas que no sean 2xx, definido una vez en la descripción de OpenAPI y referenciado por cada endpoint.
• Por cada clase de error, una URI type estable bajo el propio dominio (por ejemplo https://api.example.ch/probleme/kontingent-erschoepft), que apunte a una página con el significado, el estado típico y la reacción recomendada; la lista pertenece a la documentación de la API.
• type y title se mantienen estables entre versiones; solo detail describe el caso concreto y no devuelve sin cambios las entradas de quien hace la solicitud.
• Transportar las indicaciones de reintento en cabeceras estándar (Retry-After); el objeto de problema puede mencionarlas además.
• Los errores de validación, como campo de extensión con una lista de ruta de campo, tipo de error y mensaje, para que un cliente pueda mostrar todas las deficiencias de una vez.
• status en el cuerpo debe corresponder al estado HTTP realmente enviado; la RFC califica este campo como informativo, para que un cliente conozca el estado original incluso cuando un intermediario lo haya modificado.

Trampas

Trazas de pila, nombres de host internos o SQL en detail. Estado 200 con un objeto de error en el cuerpo, lo cual engaña tanto a las cachés como a los clientes. Renombrar clases de error sin un período de transición. Una URI type que apunta a una página 404. Introducir el formato solo en algunos endpoints, de modo que los clientes necesiten dos analizadores.