HTTP Status codes

Error Messages

For any response with a non-2xx status code, a "message" field will be present in the response. This field provides a description of the error encountered during the API process.

Error Classification

Errors returned by the API are classified into two categories: client errors (4xx) and server errors (5xx).

Client Errors (4xx): These errors are the result of improper use or incorrect requests made to the API. Examples include invalid parameters, unauthorized access, or resource not found.
ServerErrors (5xx): These errors indicate issues that originate within the API's backend systems. Server errors can range from temporary unavailability to internal server malfunctions. These errors are typically beyond the control of the API user and signify problems that need to be addressed by the system administrators.

Service Level Agreement (SLA) and System Uptime

For the purpose of calculating the Service Level Agreement (SLA) and system uptime, only server errors (5xx) are taken into consideration. Client errors (4xx) do not impact these metrics.

More information about the current system uptime, maintenance schedules, and SLA performance can be found on our status page

Status Codes

Code	Type	Description
2XX	-	The request was successfully executed and the operation was successful
400	CLIENT	The request was not processed because it contained formal errors. The service will provide as a response the details of the detected error. These errors can range from invalid payload to logic errors in the API call.
403	CLIENT	The request was not processed because there was an issue with the authentication
401	CLIENT	This may happen if you correctly populated the API key field but the key is either incorrect or not enabled.
402	CLIENT	API key used has no available credit
429	CLIENT	Indicates the user has sent too many requests in a given amount of time
500	SERVER	This is a generic error indicating a server-side problem.
504	SERVER	Gateway timeout, the server took too much time to response and closed the connection. In most cases is safe to retry this kind of transaction

Specific errors

All the errors listed below can be generated by calling the API with an invalid payload. These errors are classified as CLIENT ERRORS and will return a 400 status code.

When the API receives an invalid payload, it will respond with a 400 status code, indicating a client error. This occurs when the request parameters do not meet the required specifications or contain malformed data.

Error	Description
INVALID_PAYLOAD	The payload of the request contains fields that are not managed by the API or misses some required fields.
DUPLICATED_CUSTOMER_ID	The request was performed with the same customer_id of a previous one. Only a single request is allowed for a customer_id
FIXED_LINE	The phone number provided in the API call was a fixed line, this was introduced following the deprecation timetable
INVALID_IP	The provided IP address is not an IP, this can happen if a random string is passed instead of an IP address
MULTIPLE_PRODUCT	This can happen if multiple product call is performed without passing the claim score. More information about claims is available in the Onboarding Solution

Following is a list of detailed responses that cover the cases above:

{
  "status" : "ko",
  "message": "Multiple calls with the same customer id are not supported, please provide a different customer id",
  "errors": {
      "email" : "Detected a new value for email" 
  }
}
                                                                                                                   }

{
  "message" : "Invalid request.",
  "errors": {
    "claims" : "At least 2 other claims must be provided other than score."
  }
}

{
  "message" : "Invalid request.",
  "errors": {
    "phone_number" : "Please provide a valid phone number"
  }
}

{
  "message" : "Invalid request.",
  "errors": {
    "phone_number" : "The provided phone number is detected as FIXED_LINE"
  }
}

{
  "message" : "Invalid request.",
  "errors": {
    "ip" : "The provided value is not a valid IP address"
  }
}