Errors
Every failure is { error: { code, message } }. Branch on code — messages may be reworded.
{
"error": {
"code": "validation_failed",
"message": "The request body is invalid.",
"details": {}
}
}details is present only on some errors, such as validation_failed. The set of codes is closed:
a new code is only ever added for a new endpoint or behaviour, and an existing code never changes
meaning within a version.
Codes
| Code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Unknown, revoked or expired key; bad signature; or a signature already used once. |
invalid_timestamp | 401 | Clock more than 5 minutes off, or the timestamp is missing/malformed. Sync NTP. |
rate_limited | 429 | Over 120 requests/minute for this key. |
validation_failed | 400 | Body or query failed validation (including a malformed cursor) — see the details field. |
idempotency_key_required | 400 | POST /withdrawals needs an Idempotency-Key header. |
idempotency_conflict | 409 | That payment key was used for another payload. Recover the original payment before proceeding. |
withdrawal_not_cancellable | 409 | The payout is past pending_approval, or an approver acted first. Re-read its status. |
request_too_large | 413 | Request bodies are limited to 64 KiB. |
wallet_not_found | 404 | No such wallet in your workspace. |
withdrawal_not_found | 404 | No such withdrawal in your workspace. |
transaction_not_found | 404 | No such transaction in your workspace. |
asset_not_held | 422 | That wallet holds no such asset on that network. |
destination_not_whitelisted | 422 | The destination is not an approved, verified destination yet. |
no_approver_available | 422 | The workspace has no second approver configured. |
withdrawal_failed | 422 | The request could not be processed. |
service_unavailable | 503 | Temporary service failure. Honour Retry-After and preserve the payment key and body. |
internal_error | 500 | Something went wrong on our side. Safe to retry with the same idempotency key. |
A resource outside your workspace is always a 404, never a 403, so a response never confirms
whether an id exists elsewhere.
Retrying
| Response | Retry? |
|---|---|
429, 503 | Yes, after Retry-After seconds, with a newly signed attempt. |
500, network failure | Yes; for a payout, only with the same Idempotency-Key and body. |
401 | Not until you fix the cause: credentials, expiry, IP allowlist, clock, canonical encoding, or a resent signature. |
Other 4xx | No — correct the request first. |
See Sign a request for why every attempt needs a new signature.