> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Handle Uphold REST API errors using documented error codes and messages from the OpenAPI spec, with structured error shapes and HTTP status conventions.

Error handling is a core design principle of the API.
This helps you build robust integrations and applications that present meaningful error messages to end users.

## Comprehensive list

All possible error scenarios are enumerated as part of the OpenAPI spec, resulting in a comprehensive list of error codes and messages.
You may see these errors on every endpoint's page, by cycling through the different HTTP status codes in the response examples.

<CardGroup cols={2}>
  <Frame caption="For a comprehensive list of all possible scenarios, per API endpoint, check all the possible HTTP status codes...">
    <img src="https://mintcdn.com/uphold-d4756e17/wEVqiQJY_1BdGYCe/rest-apis/_media/error-http-status.jpg?fit=max&auto=format&n=wEVqiQJY_1BdGYCe&q=85&s=d5bc77fb64200ce9e7492655bd2e35f8" alt="Core Data Model" width="1410" height="948" data-path="rest-apis/_media/error-http-status.jpg" />
  </Frame>

  <Frame caption="... as well as all the potential errors that may be contained under that HTTP status code.">
    <img src="https://mintcdn.com/uphold-d4756e17/wEVqiQJY_1BdGYCe/rest-apis/_media/error-codes.jpg?fit=max&auto=format&n=wEVqiQJY_1BdGYCe&q=85&s=b31d5606ec35407b027b8f079319f298" alt="Core Data Model" width="1410" height="948" data-path="rest-apis/_media/error-codes.jpg" />
  </Frame>
</CardGroup>

## Consistent shape

The API follows a consistent approach to describe errors. Every error response includes a standard payload with the following fields:

```json [expandable] theme={null}
{
  // A code that identifies the error.
  "code": "country_not_supported",
  // A developer readable message describing the error.
  "message": "The country is not supported",
  // Additional details about the error.
  "details": {}
}
```

## HTTP status codes

Every error response includes an HTTP status code to indicate the nature of the error. Here are some of the most common status codes you might encounter:

* `400 Bad Request`: The request is malformed or didn't pass validation according to the endpoint's OpenAPI schema.
* `401 Unauthorized`: The request is missing authentication credentials or the provided credentials are invalid.
* `403 Forbidden`: The request is authenticated but doesn't have the necessary permissions (token scopes) to access the resource.
* `404 Not Found`: The requested resource doesn't exist.
* `409 Conflict`: The request failed due to a business logic error.
* `429 Too Many Requests`: The client has sent too many requests in a given amount of time and is being rate-limited.

However, the `code` field in the error payload is where you primarily should look as it provides a more granular description of the failure.