Códigos de estado HTTP

Los servicios de Khipu utilizan códigos de estado HTTP convencionales para indicar el éxito o el fracaso de una solicitud API. El rango 2xx se utiliza para indicar una respuesta satisfactoria y que todo ha funcionado según lo previsto, mientras que el 4xx se reserva para errores con los datos proporcionados en la solicitud (credenciales de autenticación no válidas o ausentes, llamada a un recurso inexistente). El código 500 significa que una excepción no gestionada impidió que la solicitud fuera procesada por nuestra parte.

Resumen de códigos

Código de estado HTTP	Descripción
`200 - OK`	La solicitud se ha procesado y se ha devuelto una respuesta válida. Tenga en cuenta que una respuesta puede incluir un objeto `Data` vacío y seguir considerándose correcta. Respuesta con "OK" en el campo `Status`.
`202 - Accepted`	La solicitud se ha recibido y pasado correctamente al canal asíncrono. La respuesta completa se enviará a la URL de devolución de llamada especificada en la solicitud. Respuesta con "OK" en el campo `Status`.
`400 - Bad request`	No se ha podido procesar la solicitud. Probablemente la carga útil está malformada.
`401 - Unauthorized`	Falta la cabecera de autenticación, o el valor no es válido.
`404 - Not found`	La ruta solicitada no existe en el servidor.
`500 - Server error`	Algo impidió que se ejecutara la solicitud y nuestra plataforma arrojó un error.

Manejo de errores

Estructura de errores

Cada respuesta JSON enviada por nuestros servicios incluirá un objeto Error, que se inicializará dependiendo del estado resultante de la operación.

Cuando Status=OK, el objeto Error se establece como null.
Cuando Status=ERROR. significa que la petición fue ejecutada pero no se obtuvo el resultado esperado. En este escenario el objeto Error estará compuesto por 3 elementos, todos ellos cadenas:
- Code
- Type
- Description

El detalle de cada campo es el siguiente:

Code

El valor es un código interno utilizado por Khipu para agrupar y clasificar los casos de error más comunes.

Las subdivisiones son:

Código de Error	Descripción
`A000`	Error de autenticación. Hay un problema con el token JWT (está vencido, revocado o no es válido).
`E100` - `E199`	Errores de inicio de sesión declarados por el servicio de destino, como credenciales no válidas o cuenta bloqueada.
`E2xx` - `E299`	Estos códigos se devuelven cuando el servicio de destino no está disponible o tiene problemas para servir la solicitud.
`E3xx` - `E399`	No hay datos disponibles. El proceso ha finalizado correctamente, pero no ha podido encontrar la información esperada. Por ejemplo, solicitar movimientos bancarios de un mes que aún no está disponible.
`E4xx` - `E499`	Errores de usuario relacionados con valores erróneos de los parámetros, como pasar fechas no válidas o una moneda inexistente.
`E5xx` - `E599`	Este grupo está dedicado a los errores relacionados con los servicios de Pago Automático.
`E999`	Mensaje de error personalizado que va acompañado de un texto descriptivo. Se utiliza cuando la información no puede clasificarse en los grupos anteriores.
`E000`	Se utiliza para errores genéricos que no tienen descripción.
`D000`	Falta información para completar el proceso. Esto significa que el servicio de raspado debe estar completo antes de devolver un resultado satisfactorio.
`F000`	Error durante la función de procesamiento de datos que genera la respuesta JSON.
`T000`	Tiempo de espera agotado en el servicio de destino.
`I001` - `I003`	Errores de infraestructura. Se utiliza para indicar que falta un componente interno o que las respuestas generadas no son válidas.
`P001` - `P003`	Se utiliza cuando hay errores en los parámetros de la solicitud, como una URL no válida para llamadas asíncronas.
`L000`	Se envía este código al webhook de una llamada asíncrona cuando se agota el tiempo máximo para intentar obtener los datos.

Type

Este valor indica cómo puede manejar un error, basándose en sus características. Por ejemplo, si una respuesta contiene un error que indica que las credenciales no son válidas y que la cuenta se bloqueará en el siguiente intento erróneo, probablemente no deberías reintentar la misma petición. Por otro lado, si una respuesta indica que el servicio de destino no está disponible momentáneamente, puedes reintentar la solicitud sin problemas. También existe la posibilidad de que tengamos que arreglar algo en un servicio específico, en este caso se le indicará cuándo puede reintentar su solicitud.

Tipo de Error	Descripción
`DO_NOT_RETRY`	Evita enviar la misma solicitud ya que está claro que no funcionará (se utiliza en casos de credenciales incompletas/malas o cuentas bloqueadas).
`RETRY_IMMEDIATELY`	Puede reintentar la misma solicitud sin problemas. El error se debió a un tiempo de espera de lectura o a algún contratiempo en el servicio de destino.
`WAIT_4_HOURS_BEFORE_RETRY`	Por favor, espere a que transcurra el periodo especificado antes de reintentar su solicitud. Hay trabajo que hacer por nuestra parte.

Description

Este campo explica el error con más detalle, para que comprenda mejor qué ha fallado. Puede ser el mensaje específico devuelto por la fuente de datos o una descripción genérica que se ajuste a todos los errores que utilicen un determinado código.

Ejemplo

He aquí un ejemplo del aspecto de un objeto Error en una respuesta incorrecta:

{
  "OperationId": "6baf6c19-e485-463b-ae24-a821b025c8a4",
  "Status": "ERROR",
  "Data": null,
  "AdditionalInformation": null,
  "Error": {
    "Code": "E201",
    "Type": "RETRY_IMMEDIATELY",
    "Description": "El servicio destino utilizado para la extracción de datos no se encuentra disponible."
  },
  "LifeSpan": null
}