Skip to main content
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.
CodeHTTP StatusDescription
ERR_0001500Internal error
ERR_0002—Database error
ERR_0003400Bad request
ERR_0004404Not found
ERR_0005409Conflict
ERR_0006503Service unavailable
ERR_0008401Unauthorized
ERR_0009403Forbidden
ERR_0010405Method not allowed
ERR_0011—Generic / unmapped
ERR_0012429Too 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
}