Respuestas de API

El modelo de respuesta del API agrupa los errores en categorías, adoptando el modelo de respuestas HTTP como códigos de cada grupo. Se adoptan sólo una seríe de códigos HTTP para reflejar el resultado de la operación, además, las respuestas incluyen descripción de los errores y en algunos casos el detalle del origen del error en el campo data.

Las respuestas que sean ejecutadas de manera correcta, regresarán un código HTTP 200.

Códigos de error HTTP

Código	Tipo	Campo Data	Descripción
400	Parámetros	Presente	La solicitud contiene sintaxis errónea o un parámetro incorrecto, deberá corregirse antes de realizar una nueva petición
401	Autenticación	N/A	El método de autenticación proporcionado no es válido
403	Autenticación	N/A	El método de autenticación no cuenta con permisos suficientes
404	General	N/A	No se ha encontrado el recurso solicitado
405	Sistema	N/A	Se ha hecho una solicitud a un método no soportado
409	Parámetros	N/A	Se ha realizado una solicitud que entra en conflicto con un recurso existente
412	Precondición	N/A	Una o más condiciones no se han cumplido por lo que no se puede procesar la petición
429	Sistema	N/A	Se han realizado demasiadas peticiones
500	Sistema	N/A	Ha ocurrido un error en el servidor

Procesamiento de errores

Cuando un error se presenta, en el cuerpo del mensaje estará presente un objeto error. El contenido del objeto informará el tipo de error que se presentó, así como una breve descripción. En algunos casos, el error proveerá información adicional que facilitará el proceso de debug, todo detalle adicional estará contenido en el campo data.

Ejemplo de error:

{
  "status": "error",
  "error": {
    "code": 429,
    "type": "Sistema",
    "message": "Ha excedido la tasa máxima de peticiones"
  },
  "http_code": 429,
  "datetime": "2018-09-05T15:30:49-05:00",
  "timestamp": 1536179449
}

Ejemplo de error 400 con detalle en data:

{
  "status": "fail",
  "error": {
    "code": 400,
    "type": "Parámetros",
    "message": "Error en parámetros de entrada."
  },
  "http_code": 400,
  "datetime": "2018-09-06T13:33:33-05:00",
  "timestamp": 1536258813,
  "data": {
    "errors": {
      "email": [
        "El campo email no corresponde con una dirección de e-mail válida."
      ]
    }
  }
}

Eliminar un objeto

Cuando sea eliminado un objeto se recibirá un código HTTP 200 y en el cuerpo del mensaje se indicará el detalle del objeto eliminado y la hora a la que se ejecutó el proceso.

Ejemplo de respuesta:

{
  "status": "success",
  "http_code": 200,
  "datetime": "2018-09-06T00:53:01.404Z",
  "timestamp": 0,
  "data": {
    "tarjeta": {
      "token": "string",
      "eliminacion": "2018-09-06T00:53:01.404Z"
    }
  }
}

Wrapper de Respuestas de API

En general, todas las respuestas del API incluyen un wrapper en las respuestas, el concepto detrás del wrapper es permitir una rápida interpretación de la ejecución de la petición realizada, más no del resultado, el resultado estará contenido en el campo data, algunas peticiones también podrán incluir un objeto error en el cuerpo del mensaje.

Ejemplo del wrapper:

{
  "status": "success",
  "data": {},
  "http_code": 200,
  "datetime": "2018-08-30T10:58:21-05:00",
  "timestamp": 1535644701
}

Los campos que contendrá el wrapper son descritos a continuación.

Status

El valor de "status" podrá contar con cualquiera de los siguientes valores:

1. success - indicará que la petición fue al API fue procesada correctamente. El detalle de la operación solicitada se encontrará en el campo data.
2. fail - indicará que hubo un error con los valores enviados en la petición o no se cumplió con una precondición, por ejemplo no se incluyó un vampo obligatorio.
3. error - indicará que ha ocurrido un error al procesar la petición, por ejemplo, que ha sucedido una excepción al procesar la operación.

http_code

Contendrá siempre el mismo valor del código HTTP en encabezados.

Data

Contendrá el cuerpo (datos) de la respuesta. Hay respuestas del API que no incluirán datos en el campo.