Error codes & troubleshooting
You will receive these error codes when reaching api.onramper.com (and the corresponding stg) with poorly built signatures. ###
Signature errors (401)
| Code | Action |
|---|---|
SIGNATURE_MISSING | Add sigV2 parameter |
SIGNATURE_INVALID | Check signing logic and key (see debugging below) |
SIGNATURE_VERSION_MISMATCH | Use the v2: prefix |
TIMESTAMP_MISSING | Add sigV2Timestamp |
TIMESTAMP_EXPIRED | Generate a fresh URL/request |
TIMESTAMP_FUTURE | Check server clock sync (30s skew tolerance) |
TIMESTAMP_INVALID_FORMAT | Use ISO8601 with milliseconds (.000Z) |
NONCE_MISSING | Add sigV2Nonce |
NONCE_INVALID_FORMAT | Use UUID v4 |
NONCE_REUSED | Generate a new UUID per request |
WIDGET_EXPIRED | Generate a new signed URL |
Guard errors (403)
| Code | Action |
|---|---|
IP_BLOCKED | Contact support |
DOMAIN_BLOCKED | Contact support |
DOMAIN_NOT_WHITELISTED | Register the domain with Onramper |
WALLET_BLOCKED | Use a different wallet |
General errors
| Code | Action |
|---|---|
API_KEY_MISSING (401) | Add apiKey parameter |
PARTNER_NOT_FOUND (401) | Verify your API key |
PUBLIC_KEY_NOT_CONFIGURED (401) | Send your public key to Onramper |
RATE_LIMIT_EXCEEDED (429) | Implement exponential backoff |
Debugging SIGNATURE_INVALID
SIGNATURE_INVALIDCommon causes:
- Wrong field order — query fields must be sorted alphabetically
- URL encoding mismatch — use
URLSearchParams(JS),urlencode+quote_plus(Python), orurl.Values.Encode()(Go) - Wrong key format — ensure valid PEM with headers
- Missing
apiKey— it must always be insigV2Fieldsand the canonical query - Missing fields — every field in
sigV2Fieldsmust be in the canonical query - Timestamp format — must include milliseconds (
.000Z)
Debugging steps: log the exact canonical string before signing, verify alphabetical sort order, confirm sigV2Fields lists all signed fields, check the timestamp format, and validate the nonce is UUID v4.