Error reference
Common error shapes and when they appear. Endpoint pages list errors specific to that call.
Error body shape
Most failures return JSON with success: false, a human-readable message, and optionally errors (validation bags or duplicate metadata).
Common purchase errors
| Situation | HTTP | What to do |
|---|---|---|
| Invalid / missing fields | 422 | Fix the payload. |
| Duplicate idempotency key | 409 | Requery the returned transaction id. |
| Insufficient wallet | 400 / 402 | Fund wallet, then retry with a new key. |
| Upstream / service down | 503 | Retry later; keep the same key if unsure. |
| Not found | 404 | Check path params and catalog ids. |