REST API tratamiento de errores

REST API informa de los errores devolviendo un código de respuesta HTTP apropiado, por ejemplo 404 (No encontrado), y una respuesta JSON. Cualquier código de respuesta HTTP que no esté en el rango 200 - 299 se considera un error.

Formato de respuesta de error

La respuesta está en formato JSON y en codificación UTF-8. Contiene objetos JSON anidados:
  • Un objeto JSON externo que contiene una matriz JSON única denominada error.
  • Cada elemento de la matriz es un objeto JSON que representa información sobre un error. Cada objeto JSON contiene las siguientes propiedades:
    Tipo
    Serie.
    Tipo de error.
    messageId
    Serie.
    Identificador exclusivo del mensaje en formato MQWBnnnnX. Este identificador tiene los siguientes elementos:
    MQWB
    Prefijo que muestra que el mensaje se ha originado en el API REST de MQ.
    nnnn
    Número exclusivo que identifica el mensaje.
    X
    Letra única que indica la gravedad del mensaje:
    • I si el mensajes es meramente informativo.
    • W si el mensaje es un aviso de un problema.
    • E si el mensaje indica que se ha producido un error.
    • S si el mensaje indica que se ha producido un error.
    mensaje
    Serie.
    Una descripción del error.
    explanation
    Serie.
    Una explicación del error.
    acción
    Serie.
    Una descripción de los pasos que se pueden realizar para resolver el error.
    qmgrName
    [z/OS]Este campo sólo está disponible para z/OS® cuando el gestor de colas es miembro del grupo de colas compartidas. Debe haber especificado el parámetro de consulta opcional commandScope o el atributo queueSharingGroupDisposition.
    Serie.
    El nombre del gestor de colas que ha experimentado el error.
    Este campo no es aplicable para messaging REST API.
    completionCode
    Este campo solo está disponible cuando type es pcf, java o rest.
    Número.
    Código de terminación MQ asociado al error.
    reasonCode
    Este campo solo está disponible cuando type es pcf, java o rest.
    Número.
    Código de razón MQ asociado al error.
    exceptions
    Este campo solo está disponible cuando type es java.
    Matriz.
    Una matriz de excepciones Java o JMS de cadena. Cada elemento de la matriz de excepciones contiene una matriz de series stackTrace.
    La matriz de series stackTrace contiene los detalles de cada excepción divididos en líneas.
[z/OS]

Errores con los grupos de compartición de colas

En un grupo de compartición de colas, se puede especificar un parámetro de consulta opcional de commandScope en determinados mandatos. Este parámetro permite propagar el mandato a otros gestores de colas del grupo de compartición de colas. Cualquiera de estos mandatos puede fallar independientemente, por lo que algunos mandatos terminarán satisfactoriamente y otros fallarán para el grupo de compartición de colas.

En los casos en los que un mandato falla parcialmente, se devuelve un código de error HTTP 500. Para cada gestor de colas que genera un error, se devuelve información sobre ese error como un elemento en la matriz JSON error. Para cada gestor de colas que ejecuta correctamente el mandato, se devuelve el nombre del gestor de colas como un elemento en una matriz JSON success.

Ejemplos

  • El ejemplo siguiente muestra la respuesta de error a un intento de obtener información sobre un gestor de colas que no existe:
    "error": [
   {
      "type": "rest",
      "messageId": "MQWB0009E",
      "message": "MQWB0009E: Could not query the queue manager 'QM1'",
      "explanation": "The MQ REST API was invoked specifying a queue manager name which cannot be located.",
      "action": "Resubmit the request with a valid queue manager name or no queue manager name, to retrieve a list of queue managers. " 
   }
]
  • [z/OS]El ejemplo siguiente muestra la respuesta de error a un intento de suprimir una cola en un grupo de compartición de colas que no existe para algunos gestores de colas:
    "error" : [
  {
    "type": "rest",
    "messageId": "MQWB0037E",
    "message": "MQWB0037E: Could not find the queue 'missingQueue' - the queue manager reason code is 3312 : 'MQRCCF_UNKNOWN_OBJECT_NAME'",
    "explanation": "The MQ REST API was invoked specifying a queue name which cannot be located.",
    "action": "Resubmit the request with the name of an existing queue, or with no queue name to retrieve a list of queues.",  
    "qmgrName": "QM1"
  },
  {
    "type": "rest",
    "messageId": "MQWB0037E",
    "message": "MQWB0037E: Could not find the queue 'missingQueue' - the queue manager reason code is 3312 : 'MQRCCF_UNKNOWN_OBJECT_NAME'",
    "explanation": "The MQ REST API was invoked specifying a queue name which cannot be located.",
    "action": "Resubmit the request with the name of an existing queue, or with no queue name to retrieve a list of queues.",  
    "qmgrName": "QM2"
  }
],
"success" : [{"qmgrName": "QM3"}, {"qmgrName": "QM4"}]

Errores con solicitudes MFT

Si los servicios de MFT REST API no están habilitados e invoca el MFT REST API, recibirá la excepción siguiente:
{"error": [{
  "action": "Enable the Managed File Transfer REST API and resubmit the request.",
  "completionCode": 0,
  "explanation": "Managed File Transfer REST calls are not permitted as the service is disabled.",
  "message": "MQWB0400E: Managed File Transfer REST API is not enabled.",
  "msgId": "MQWB0400E",
  "reasonCode": 0,
  "type": "rest"
}]}
Si los servicios MFT REST API están habilitados y el gestor de colas de coordinación no está establecido en el archivo mqwebuser.xml, recibirá la siguiente excepción:
{"error": [{
  "action": "Set the coordination queue manager name and restart the mqweb server.",
  "completionCode": 0,
  "explanation": "Coordination queue manager name must be set before using Managed File Transfer REST services.",
  "message": "MQWB0402E: Coordination queue manager name is not set.",
  "msgId": "MQWB0402E",
  "reasonCode": 0,
  "type": "rest"
}]}