Skip to content

Errors and troubleshooting

HTTP codes

Code	Meaning	When it occurs
`200`	OK	Successful request.
`403`	Forbidden	`X-Device-Id` header missing or invalid.
`404`	Not Found	Non-existent route, or invalid currency on order creation, or amount below the minimum, or malformed redirect URLs.
`429`	Too Many Requests	Rate limit exceeded. Use `Retry-After`.
`500`	Internal Server Error	Backend error. Retry with exponential backoff; if it persists, contact support.

How to interpret a 404 on `POST /orders/`

The 404 groups several causes. The response body typically points to the specific one:

Invalid currency — input_currency does not match any symbol from GET /currencies.
Minimum amount not met — expected_output_amount below the currency’s min_amount.
Redirect URLs missing or malformed (merchant_urlok, merchant_urlko).

Quick troubleshooting

I get 403 on every request

Verify the header is named exactly X-Device-Id (with hyphens, case-insensitive in HTTP but use the exact form anyway).
Verify the key has no leading/trailing whitespace.
Verify the device is not disabled in the dashboard.

I get 404 on `POST /orders/` with a symbol that does exist

Call GET /currencies and copy the exact symbol. Symbols are granular per network (for example USDC_POLYGON_NXTB, not just USDC).
Verify letter case.

The webhook never arrives

Check that notification_url points to a public URL (not localhost).
Use HTTPS.
Confirm your endpoint returns 200 quickly (< 5 s).
Verify your server firewall.

The webhook signature does not match

Common causes (in order of frequency):

You did not decode the Secret Key from hex to bytes.
You parsed and re-serialized the JSON body (use the raw body).
You added a trailing newline to the body.
You concatenated body + nonce instead of nonce + body.
You compared with == instead of timing-safe.

Validate with the official test vectors.