Errors

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

{
  "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).

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.

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

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

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

{
  "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).

{
  "error_code": "ERR_0009",
  "message": "Forbidden",
  "data": null
}

404 — Not Found

Returned when the requested endpoint does not exist.

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

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

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

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

{
  "error_code": "ERR_0001",
  "message": "Internal error",
  "data": null
}

503 — Service Unavailable

Returned when a third-party service fails to respond.

{
  "error_code": "CUR_0100",
  "message": "Error",
  "data": null
}

Introduction

Ripio Wallet

Ripio Trade

Note: field-level context in `data`

Generic error codes

400 — Bad request

Missing or wrong serializer fields

Single field error

Non-serializer error (generic)

401 — Unauthorized

User not found

403 — Forbidden

404 — Not Found

405 — Method Not Allowed

409 — Conflict

429 — Too Many Requests

500 — Internal Error

503 — Service Unavailable

​Note: field-level context in data

​Generic error codes

​400 — Bad request

​Missing or wrong serializer fields

​Single field error

​Non-serializer error (generic)

​401 — Unauthorized

​User not found

​403 — Forbidden

​404 — Not Found

​405 — Method Not Allowed

​409 — Conflict

​429 — Too Many Requests

​500 — Internal Error

​503 — Service Unavailable

Note: field-level context in `data`

Generic error codes

400 — Bad request

Missing or wrong serializer fields

Single field error

Non-serializer error (generic)

401 — Unauthorized

User not found

403 — Forbidden

404 — Not Found

405 — Method Not Allowed

409 — Conflict

429 — Too Many Requests

500 — Internal Error

503 — Service Unavailable