Response envelope
Every response, successful or not, uses the same envelope:{
"code": 100004,
"message": "Amount is below the minimum for this route.",
"displayError": "Amount is below the minimum for this route.",
"traceId": "b1f2c3d4e5f60718293a4b5c6d7e8f90"
}
| Field | Description |
|---|---|
code | Application code. 0 means success. Branch your logic on this, not on the HTTP status or the message text |
message | success on success. On error: the displayError text when there is one, otherwise the code’s label from the table below (for example invalid_args_err). Never contains internal or provider error details |
displayError | Optional message that is safe to show your end user. When absent, show your own copy keyed on code |
traceId | Request id in Rampnow’s logs, also returned in the X-Request-ID header. Include it when you contact support |
data | The response body on success |
Don’t parse
message for meaning: its text can change. Use code in your logic and displayError (or your own copy) for user-facing text.HTTP statuses
| HTTP status | When |
|---|---|
200 | Success, and some failures (see below) |
400 | Invalid arguments (100004, 100015) |
401 | Authentication or authorisation failed (100001, 100002) |
404 | Resource not found (100000) |
409 | Conflict (100005) |
415 | The Accept header doesn’t allow JSON. Plain-text body, no envelope |
500 | Every other error code, including business errors such as an invalid quote |
501 | Not implemented (100011) |
Check
code even when the HTTP status is 200. Some failures currently return 200:- A malformed JSON body, or one that fails field validation, returns
200withcode100008(internal_err). Fix the request; don’t retry it unchanged. - A quote for an unsupported pair, or an amount outside the route’s limits, returns
200withcode0, empty quote data and amessagesuch asNo routes found for the selected options.
Retry-After.
Error codes
| Code | Label | HTTP | Category | Retry? | Typical cause on partner endpoints |
|---|---|---|---|---|---|
0 | success | 200 | Success | — | Request succeeded |
100000 | not_found_err | 404 | Client | No | Resource doesn’t exist, or no partner wallet is configured for an order without wallet |
100001 | not_authenticated_err | 401 | Auth | No | Missing credentials |
100002 | not_authorized_err | 401 | Auth | No | Any authentication failure: bad key, signature or timestamp |
100003 | unknown_err | 500 | Server | Yes | Unexpected server error |
100004 | invalid_args_err | 400 | Client | No | A field is missing or invalid: wallet address, amount below the route minimum, checkout not enabled for your account |
100005 | conflict_err | 409 | Client | No | The wallet address already belongs to another customer |
100006 | db_err | 500 | Server | Yes | Temporary storage error |
100007 | marshal_err | 500 | Server | Yes | Temporary serialization error |
100008 | internal_err | 500 or 200 | Server / Client | 500: Yes. 200: No | 500: internal error. 200: malformed or invalid request body |
100009 | http_err | 500 | Upstream | Yes | A payment or liquidity provider call failed |
100010 | setup_err | 500 | Server | No | Configuration problem on Rampnow’s side. Contact support |
100011 | not_implemented_err | 501 | Client | No | Feature not available |
100012 | ext_api_err | 500 | Upstream | Yes | A provider returned an error |
100013 | timeout_err | 500 | Upstream | Yes | A provider call timed out |
100014 | expired_err | 500 | Business | No | The order expired. Create a new order |
100015 | invalid_err | 400 | Client | No | Invalid data in the request |
100017 | request_err | 500 | Upstream | No | A provider rejected the request. Contact support with the traceId |
100018 | blocked_err | 500 | Business | No | Your partner account or the wallet is inactive or blocked |
100019 | blacklisted_err | 500 | Business | No | The user, wallet or entity is blacklisted |
100020 | retry_exceeded_err | 500 | Business | No | Too many attempts for this operation |
100021 | not_supported_err | 500 | Business | No | Unsupported option, for example an orderType other than buy or sell |
100023 | invalid_quote_err | 500 | Business | No | The amount can’t be quoted: outside the route limits, or both or neither of srcAmount/dstAmount set |
100024 | server_err | 500 | Upstream | Yes | A provider had a server error |
100025 | request_timeout_err | 500 | Upstream | Yes | A provider request timed out |
100026 | payload_size_err | 500 | Upstream | No | A provider rejected the payload size |
100027 | rate_limit_err | 500 | Upstream | Yes | A provider rate-limited Rampnow. Retry with a longer backoff |
100028 | bad_gateway_err | 500 | Upstream | Yes | A provider gateway error |
100029 | service_unavailable_err | 500 | Upstream | Yes | A provider is temporarily unavailable |
100030 | gateway_timeout_err | 500 | Upstream | Yes | A provider gateway timed out |
100031 | invalid_method_err | 500 | Upstream | No | A provider rejected the request method. Contact support |
100032 | unprocessable_entity_err | 500 | Upstream | No | A provider rejected the request content |
Retrying
- Retry only codes marked Yes, with exponential backoff (for example 1s, 2s, 4s, up to 5 attempts).
- Never retry
4xxresponses or business errors unchanged. Fix the request or ask the user to change it. - Quotes, configuration endpoints and Get Order are safe to retry.
Don’t blindly retry Create Order (
/ext/ramp_order/checkout). Orders aren’t de-duplicated by externalOrderUid, so a retry after a timeout or 5xx can create a second order. First call Get Order with your externalOrderUid, and retry only if orderList is empty.