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`

Common causes:

Wrong field order — query fields must be sorted alphabetically
URL encoding mismatch — use URLSearchParams (JS), urlencode + quote_plus (Python), or url.Values.Encode() (Go)
Wrong key format — ensure valid PEM with headers
Missing apiKey — it must always be in sigV2Fields and the canonical query
Missing fields — every field in sigV2Fields must 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.

Updated 20 days ago

Did this page help you?