Una respuesta fallida de la API debe ayudar a entender el problema. Revísala desde la perspectiva del cliente y del soporte. EMPIEZA POR ESCENARIOS En pruebas, prepara un registro ausente, un parámetro inválido y un fallo temporal. Anota el siguiente paso esperado: corregir la entrada o intentarlo después. No crees pedidos reales solo para probar mensajes. UNA ESTRUCTURA COMPARTIDA RFC 9457 define Problem Details para API HTTP y el tipo application/problem+json. Distingue type, identificador del tipo de problema, y detail, explicación del caso concreto. El cliente no necesita adivinar una estructura distinta para cada error. SEPARA LOS PÚBLICOS El cliente necesita un siguiente paso breve; el desarrollador, una forma estable de reconocer la situación. No bases la lógica únicamente en mensajes traducidos. Acuerda qué información es pública y excluye contraseñas, tokens, consultas internas y conversaciones privadas. REVISA EL RECORRIDO Guarda un ejemplo sin datos sensibles y comprueba su presentación. ¿Convierte el formulario cualquier fallo en éxito? ¿Puede soporte localizar la consulta sin pedir secretos? Asigna responsable y criterio de resolución a cada escenario. Al preparar la web de un dominio del catálogo, incorpora ejemplos de error al encargo junto a los recorridos correctos. Así discutirás el comportamiento antes del lanzamiento y no después de la primera consulta confusa. Imagen: nueva fotoilustración generada con IA para este artículo; escena conceptual, no una fotografía documental. Catálogo de dominios: https://domainevery.com/es/domains Fuentes primarias: https://www.rfc-editor.org/rfc/rfc9457.html
