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

# Errors

> Error reference for the Ripio Wallet API.

All responses — success and error — share the same envelope:

```json theme={null}
{
  "error_code": null,
  "message": null,
  "data": { }
}
```

* **Success**: `error_code` and `message` are `null`; `data` holds the payload.
* **Error**: `error_code` and `message` are populated; `data` is `null` unless there are multiple field-level validation errors (see [400 — Bad request](#400---bad-request)).

### Note: field-level context in `data`

For multi-field validation errors (e.g. a form submission with several invalid inputs), `data` carries the full error structure so the client can map each error back to the right input field. For all other errors `data` is `null`.

***

### Generic error codes

These codes are used as fallbacks when the upstream service does not return a specific error code. Upstream-specific codes (e.g. `TXN_0420`, `CVU_1005`) are passed through unchanged and always take precedence.

| Code       | HTTP Status | Description         |
| ---------- | ----------- | ------------------- |
| `ERR_0001` | 500         | Internal error      |
| `ERR_0002` | —           | Database error      |
| `ERR_0003` | 400         | Bad request         |
| `ERR_0004` | 404         | Not found           |
| `ERR_0005` | 409         | Conflict            |
| `ERR_0006` | 503         | Service unavailable |
| `ERR_0008` | 401         | Unauthorized        |
| `ERR_0009` | 403         | Forbidden           |
| `ERR_0010` | 405         | Method not allowed  |
| `ERR_0011` | —           | Generic / unmapped  |
| `ERR_0012` | 429         | Too many requests   |

***

## 400 — Bad request

Returned when something is missing or wrong with a request.

### Missing or wrong serializer fields

When multiple fields are invalid, `error_code` and `message` are taken from the first field error. All field errors are preserved in `data`.

```json theme={null}
{
  "error_code": "NET_0001",
  "message": "This field is required.",
  "data": {
    "network": [
      {
        "code": "NET_0001",
        "detail": "This field is required."
      }
    ],
    "currency": [
      {
        "code": "CURR_0001",
        "detail": "Currency not supported."
      }
    ]
  }
}
```

### Single field error

When only one field is invalid, `data` is `null`.

```json theme={null}
{
  "error_code": "NET_0001",
  "message": "This field is required.",
  "data": null
}
```

### Non-serializer error (generic)

Errors not associated with a specific input field (e.g. business-logic validation). `data` is `null`.

```json theme={null}
{
  "error_code": "ACC_0002",
  "message": "Ensure your account has validation level 4",
  "data": null
}
```

***

## 401 — Unauthorized

Returned when the request cannot be authenticated.

### User not found

The token is valid but the user referenced by it does not exist.

```json theme={null}
{
  "error_code": "ERR_0008",
  "message": "User not found",
  "data": null
}
```

***

## 403 — Forbidden

Returned when the token is valid but lacks the permissions required by the endpoint.

Every endpoint requires at least the `general_data_read` permission. Additional permissions may be required per endpoint (e.g. `balance_read` for the balance endpoint).

```json theme={null}
{
  "error_code": "ERR_0009",
  "message": "Forbidden",
  "data": null
}
```

***

## 404 — Not Found

Returned when the requested endpoint does not exist.

```json theme={null}
{
  "error_code": "ERR_0004",
  "message": "Not found",
  "data": null
}
```

***

## 405 — Method Not Allowed

Returned when the HTTP method used is not supported by the endpoint.

```json theme={null}
{
  "error_code": "ERR_0010",
  "message": "Method not allowed",
  "data": null
}
```

***

## 409 — Conflict

Returned when some internal conflict occurred within a request, for example a duplicate entity or an exceeded limit.

```json theme={null}
{
  "error_code": "BALANCE_0001",
  "message": "Cant create balance",
  "data": null
}
```

***

## 429 — Too Many Requests

Returned when the client exceeds the rate limit for an endpoint.

```json theme={null}
{
  "error_code": "ERR_0012",
  "message": "Request was throttled.",
  "data": null
}
```

***

## 500 — Internal Error

Returned when an unexpected error occurs on the server. If this error persists, contact Ripio support.

```json theme={null}
{
  "error_code": "ERR_0001",
  "message": "Internal error",
  "data": null
}
```

***

## 503 — Service Unavailable

Returned when a third-party service fails to respond.

```json theme={null}
{
  "error_code": "CUR_0100",
  "message": "Error",
  "data": null
}
```