Definir respuestas de error personalizadas

Definir respuestas de error personalizadas

Resumen

Además de las plantillas de salida para las respuestas exitosas, cada método puede tener plantillas de error: definen qué contenido y qué código HTTP recibe el cliente cuando algo falla.

Las plantillas de error se configuran por formato de salida. Cada formato que agregue en Plantillas de output (por ejemplo JSON o XML) tiene su pestaña en Plantillas de error, y en cada pestaña se definen todas las plantillas de error de ese formato. Así, un pedido en JSON recibe el error en JSON y uno en XML lo recibe en XML.

Cuando no hay ninguna plantilla de error que aplicar, ni del método ni de la cuenta, Vor-Tex responde con su mensaje estándar, que se puede pedir en inglés, español o portugués. Ver Idioma de las respuestas de error.

Antes de comenzar

1. Elegir cómo se decide el código HTTP

Al crear o editar un método, vaya a la sección Plantillas de error. Arriba hay dos opciones excluyentes:

  • Mapear códigos HTTP (opción por defecto): cada error tiene su tarjeta, donde usted elige la plantilla y el código de respuesta.
  • Trasladar el código HTTP de respuesta del origen de datos: cuando el origen es un servicio web y responde con error, el cliente recibe el mismo código que devolvió el origen, por ejemplo 404 o 500. Con esta opción se descartan los códigos que haya mapeado para los errores por código; solo se conservan los de ERROR GENÉRICO, ERROR DE VALIDACIÓN DE PARÁMETRO y ERROR FUERA DE SERVICIO.

Sección Plantillas de error del método, con la pestaña de formato y las tarjetas de error

2. Configurar las plantillas de cada formato

Debajo de las opciones hay una pestaña por cada formato de salida del método. En cada pestaña configure las tarjetas de error. Cada tarjeta tiene:

  • Plantilla: la plantilla que arma el contenido de la respuesta. Con el botón ... puede elegir Nueva plantilla, Editar plantilla o Eliminar plantilla.
  • Código de respuesta: el código HTTP que recibe el cliente. Si no elige ninguno, se usa el código del error.

Las tarjetas se agrupan así:

  • ERROR GENÉRICO: se usa para cualquier error que no tenga una plantilla propia.
  • ERROR DE VALIDACIÓN DE PARÁMETRO: se usa cuando uno o más parámetros de la solicitud no pasan la validación, por ejemplo un parámetro obligatorio que falta o un valor fuera de rango.
  • ERROR FUERA DE SERVICIO: se usa cuando el método está fuera de servicio. Ver Programar franjas fuera de servicio.
  • Errores por código, en el bloque "Configure como se mostrarán los errores de este método específicamente según formato y código de respuesta":
    • 204 - NO DATA FOUND: el origen respondió bien pero sin contenido, o la vista aplicó un filtro que no dio resultados. Sin plantilla, la respuesta es un 204 sin contenido.
    • 206 - PARTIAL CONTENT: la respuesta del origen llegó incompleta.
    • 401 - UNAUTHORIZED: el origen rechazó la autenticación.
    • 404 - NOT FOUND: el origen respondió 404.
    • 408 - REQUEST ACCEPTED: el origen está demorando en responder. La plataforma sigue esperando la respuesta y el cliente puede volver a consultar más tarde. Responde siempre con código 202.
    • 409 - PIPELINE RESPONSE: respuesta de un pipeline. Responde siempre con código 202.
    • 500 - INTERNAL SERVER ERROR: el origen respondió 500.
    • 502 - WEBSERVICE RESPONSE ERROR: el origen respondió con un error que no corresponde a los códigos anteriores. Es también la plantilla que se usa con la opción Trasladar el código HTTP de respuesta del origen de datos.

Si un error no tiene plantilla en el formato pedido, se usa la de ERROR GENÉRICO del método en ese formato. Si tampoco existe, se usa la plantilla de error de la cuenta.

3. Escribir la plantilla

Al elegir Nueva plantilla o Editar plantilla se abre el editor. La plantilla se escribe con Jinja y usa el objeto result como variable de contexto. Escriba un nombre en Nombre de la plantilla y haga clic en Listo.

A la derecha del editor hay dos pestañas:

  • Referencias: lista las variables y los filtros disponibles para ese tipo de error, con su descripción.
  • Agente de IA (beta): puede pedirle que le arme o corrija la plantilla.

Editor de plantilla de error de validación con la pestaña Referencias

Variables principales:

  • En todas las plantillas de error: result.error_code, result.error_message y request.traceid (el identificador de la solicitud).
  • En los errores del origen: result.fields.statusCode, result.fields.reason y result.fields.content, con la respuesta que devolvió el origen.
  • En ERROR DE VALIDACIÓN DE PARÁMETRO:
    • result.error_message: el primer error de validación.
    • result.error_messages: la lista con todos los errores de validación, en orden. El primero es el mismo que error_message.
    • result.path: la URL invocada, sin comillas ni credenciales.
    • result.method: el método HTTP de la solicitud, por ejemplo GET o POST.
    • result.timestamp: el momento de la respuesta, en milisegundos.
  • En ERROR FUERA DE SERVICIO también están disponibles result.path y result.method.

Ejemplo de plantilla JSON para el error de validación, que devuelve todos los errores juntos:

{
  "message": "{{ result.error_message }}",
  "errors": {{ result.error_messages | jsonify }},
  "url": "{{ result.path }}",
  "method": "{{ result.method }}",
  "traceId": "{{ request.traceid }}"
}

Si se envía una solicitud con dos parámetros inválidos, errors trae los dos mensajes y el cliente puede corregir todo de una vez.

Resultado esperado

Cuando falla una solicitud al método, el cliente recibe el error en el mismo formato que pidió (JSON, XML u otro), con el contenido de la plantilla y el código HTTP que usted configuró.

Errores frecuentes

  • Un pedido en XML recibe el error en JSON, o al revés: la plantilla está cargada en la pestaña de otro formato. Revise la pestaña del formato pedido.
  • Se aplica la plantilla genérica en lugar de la específica: ese error no tiene plantilla en el formato pedido. Agréguela en la pestaña correspondiente.
  • El código HTTP no es el que mapeó: con Trasladar el código HTTP de respuesta del origen de datos, los códigos de los errores por código se descartan y se usa el del origen. Además, 408 y 409 responden siempre 202.
  • La plantilla de validación muestra un solo error: use result.error_messages en lugar de result.error_message.

Artículos relacionados