Error Handling

This API employs a unified approach to error handling across all endpoints. Meaningful error messages with detailed descriptions of the error's cause are returned in a consistent JSON format:

{
  "errorCode": "INVALID_REQUEST_DATA",
  "message": "Invalid create payment return request.",
  "warnings": [
    {
      "position": "reason",
      "issue": "Must be at least 6 characters and not more than 255."
    }
  ]
}

Our API validation is designed to provide comprehensive feedback. Unlike some systems that stop at the first error, we check all aspects of your request and report all issues at once. This helps you quickly identify and correct any problems. We validate both technical requirements (like data format) and business rules (like required information)

Certain business rules require contextual checks beyond basic schema validation. Communicating these requirements clearly and simply can be difficult. Therefore, we prioritize a unified and consistent language in our error messages, mirroring the terminology used throughout the API documentation. We strive for a self-documenting API, minimizing the need for extensive external documentation.

We adhere to standard REST and HTTP error conventions and status codes.

400 status codes indicate client errors, with details provided in the payload
404 status codes indicate that the requested resource could not be found
409 status codes signal data conflicts,
and 50x codes represent server errors.

The errorCode field provides additional information about the specific cause of the error. Possible values for errorCode include:

INTERNAL_ERROR: An error occurred within the API.
INVALID_REQUEST: The request is invalid (this code is also used when warnings are present).
INVALID_REQUEST_DATA: The request data is invalid.
INVALID_REQUEST_URL: The request URL is invalid.
INVALID_REQUEST_HEADERS: The request headers are invalid.
INVALID_REQUEST_URL_PARAMS: The URL parameters are invalid.
INVALID_REQUEST_QUERY_PARAMS: The query parameters are invalid.
RESOURCE_MISSING: The requested resource is missing.
AUTHENTICATION_FAILED: Authentication failed (You couldn't log in)
AUTHORIZATION_FAILED: Authorization failed (You don't have permission to do that)
UNSUPPORTED_MEDIA_TYPE: The request's media type is unsupported.

The "warnings" field (which may be omitted if there are no specific warnings) indicates the precise location within the request payload of any erroneous or invalid data.

Example 1: Invalid Request Data

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Cannot update address for not ACTIVE payee."
}

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Invalid Payment input",
    "warnings": [
        {
            "position": "amount",
            "issue": "Maximum decimal scale of money amounts can be 2."
        }
    ]
}

Multiple issues displayed in single response:

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Invalid Business End User details.",
    "warnings": [
               {
            "position": "businessPersons",
            "issue": "Total ownership of all people should be less than 100."
        },
        {
            "position": "business.companyName",
            "issue": "Should contain at least one alphanumeric character and can contain spaces and any of the following special characters [',£€¥‘’:/«»“”.?\\-+()], but was ' '."
        },
        {
            "position": "business.website",
            "issue": "Should be walid URL, but was 'https://latamcosa.com/'."
        }
}

Example 2: Resource Missing

{
    "errorCode": "RESOURCE_MISSING",
    "message": "Payee with 'pye_xyz123zyx321' id does not exist."
}

Example 3: Conflict

When the used scheme don't match to / from bank details

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Invalid Payment input.",
    "warnings": [
        {
            "position": "paymentScheme",
            "issue": "possible values: [SCT]"
        }
    ]
}

When trying to change the status of an account that has been permanently closed

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Account closed permanently",
    "warnings": [
        {
            "position": "status",
            "issue": "changes are forbidden"
        }
    ]
}

Example the 4: Internal Server Error

{
  "errorCode": "INTERNAL_ERROR",
  "message": "Internal error has occurred"
}