# HTTP Codes

Khipu services use standard HTTP status codes to indicate the success or failure of an API request. The `2xx` range is used to indicate a successful response and that everything worked as intended, while `4xx` is reserved for errors with the data provided in the request (missing or invalid authentication credentials, call to a non-existent resource). The `500` code means that an unhandled exception prevented the request from being processed on our end.

## Code summary

| HTTP Status Code | Description |
|  --- | --- |
| `200 - OK` | The request has been processed and a valid response has been returned. Note that a response can contain an empty `Data` object and still be considered correct. Response with "**OK**" in the `Status` field. |
| `202 - Accepted` | The request has been received and correctly passed to the asynchronous channel. The full response is delivered to the callback URL specified in the request. Response with "**OK**" in the `Status` field. |
| `400 - Bad request` | The request could not be processed. The payload is probably malformed. |
| `401 - Unauthorized` | Authentication header missing or invalid value. |
| `404 - Not found` | The requested path does not exist on the server. |
| `500 - Server error` | Something was preventing the request from being executed and an error was thrown by our platform. |


# Errors

## Error structure

Each JSON response sent by our services contains an `Error` object, which is initialized depending on the resulting status of the operation.

* If `Status=OK`, the `Error` object is set to `null`.
* If `Status=ERROR`, it means that the request was executed but the expected result was not achieved. In this scenario, the `Error` object is made up of 3 elements, all of which are strings:
  * Code
  * Type
  * Description


The details of each field are as follows:

### Code

The value is an internal code used by Khipu to group and classify the most common errors.

The subdivisions are:

| Error Code | Description |
|  --- | --- |
| `A000` | Authentication error. There is a problem with the JWT token (it is either expired, revoked or invalid). |
| `E100` - `E199` | Logon errors reported by the target service, such as invalid credentials or blocked account. |
| `E2xx` - `E299` | These codes are returned if the destination service is unavailable or has problems serving the request. |
| `E3xx` - `E399` | No data available. The process completed successfully, but could not find the expected information. For example, requesting bank transactions for a month that is not yet available. |
| `E4xx` - `E499` | User errors related to bad parameter values, such as invalid dates or a non-existent currency. |
| `E5xx` - `E599` | This group is dedicated to errors related to automatic payment services. |
| `E999` | User-defined error message accompanied by a descriptive text. Used when the information does not fit into the above groups. |
| `E000` | Used for generic errors with no description. |
| `D000` | Missing information to complete the process. This means that the scraping service must be completed before it returns a successful result. |
| `F000` | Error during the data processing function that generates the JSON response. |
| `T000` | Timeout while scraping the target service. |
| `I001` - `I003` | Infrastructure error. Used to indicate a missing internal component or invalid generated responses. |
| `P001` - `P003` | Used when there are errors in the request parameters, such as an invalid URL for asynchronous calls. |
| `L000` | This code is sent to the webhook of an asynchronous call when the timeout for trying to retrieve the data is reached. |


### Type

This value tells you how to handle an error based on its characteristics. For example, if a response contains an error indicating that the credentials are invalid and the account will be blocked on the next bad attempt, you probably should not retry the same request. On the other hand, if a response indicates that the target service is temporarily unavailable, you can safely retry your request. It is also possible that we need to fix something in a particular service, in which case we will tell you when you can retry your request.

| Error Type | Description |
|  --- | --- |
| `DO_NOT_RETRY` | Avoid sending the same request when it is clear that it will not work (used in cases of incomplete/bad credentials or blocked accounts). |
| `RETRY_IMMEDIATELY` | You can safely retry the same request. The error was due to a read timeout or a hiccup in the destination service. |
| `WAIT_4_HOURS_BEFORE_RETRY` | Please wait for the specified amount of time to elapse before submitting your request again. There's some work to be done on our end. |


### Description

This field explains the error in more detail to help you understand what went wrong. This can be the specific message returned by the data source, or a generic description that applies to all errors with a particular code.

## Example

Here is an example of what an `Error` object looks like in a bad response:


```json
{
  "OperationId": "6baf6c19-e485-463b-ae24-a821b025c8a4",
  "Status": "ERROR",
  "Data": null,
  "AdditionalInformation": null,
  "Error": {
    "Code": "E201",
    "Type": "RETRY_IMMEDIATELY",
    "Description": "The target service used for data extraction is not available."
  },
  "LifeSpan": null
}
```