Errors

Errors return a JSON body with an error field, and often a message with more detail:

{
  "error": "You haven't set up a wallet address for the Polygon network",
  "message": "Please configure a Polygon-specific wallet in your merchant settings before accepting payments on this network.",
  "network": "polygon"
}

Status codes

Code	Meaning
400	the request was rejected, read error
401	missing or invalid credentials
404	no such endpoint, or no such resource on the endpoints that use it
500	something failed server-side

An unknown payment ID returns 500

Reading a payment that does not exist returns 500, not 404:

{ "success": false, "error": "Failed to query payment status" }

This affects the payment and deposit read endpoints. Other endpoints do return 404 for a resource that does not exist, so the behaviour is not consistent across the API. It is documented because it is what happens today: do not treat 500 on these routes as necessarily meaning an outage. Check the id first.

Because a change from 500 to 404 would alter the status code for an existing outcome, it counts as breaking under our versioning policy and will not land silently in v1.

Retrying

500 responses on read endpoints are safe to retry.

Retrying a write is only safe if the server can recognise the repeat. Send an Idempotency-Key header, or at least the same orderId. See Retrying safely.