---
updatedAt: 2025-06-12T23:53:48.000Z
agentTools:
  projectIndex: https://docs.fiatrepublic.com/llms.txt
---

# 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:

```json json
{
  "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.

<br />

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.

<br />

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**

```json 400 Bad Request
{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Cannot update address for not ACTIVE payee."
}
```

```json 400 Bad Request
{
    "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:

```Text 400 Bad Request
{
    "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**

```json 404 Not Found
{
    "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

```json 409 Conflict
{
    "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

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

**Example the 4: Internal Server Error**

```json 500 Server Error
{
  "errorCode": "INTERNAL_ERROR",
  "message": "Internal error has occurred"
}
```