Errors

Status codes per endpoint and how to handle them.

Error format

Every error is JSON with a single message:

{ "error": "This key cannot perform this action." }

Match on the HTTP status code, not the message text. Messages are for people and may be reworded.

Common statuses

Status	Meaning	What to do
`400`	The request is invalid (a missing or malformed field, or a missing `Idempotency-Key`).	Fix the request. A corrected retry may reuse the same `Idempotency-Key`.
`401`	The key is missing, unknown or revoked. An unknown or revoked key gets the same message; a missing or malformed `Authorization` header gets its own.	Check the `Authorization` header and the key.
`403`	The key lacks the scope for this endpoint, or your account is not active.	Use a key with the right scope.
`404`	Not found, including a record that belongs to another account or the other environment. You never get `403` for someone else's record.	Check the ID and which key you used.
`409`	An `Idempotency-Key` conflict, or a confirm on a transaction that is no longer awaiting payment.	For a key conflict, retry with a new key. For a confirm, read the transaction's `status`.
`422`	Refused by a business rule: a missing or unknown `purpose`, a missing or invalid `purpose_detail` when `purpose` is `other`, screening, the sender's limit, the sender's KYC status, or a masked payout account.	Read the message and the transaction's `status`; do not retry unchanged.
`429`	Rate limit exceeded.	Wait for the `Retry-After` header, then retry with jitter.
`503`	Live exchange rates are briefly unavailable, or another transfer for the same sender is in progress. Nothing was created.	Retry later. A `POST /transactions` retry may reuse its `Idempotency-Key`.

A 422 from screening still records the attempt as a blocked transaction: a repeat with the same Idempotency-Key returns it with 200. Always read status and compliance_status in the body, not only the status code.

Statuses per endpoint

Every status each endpoint can return:

Endpoint	Status codes
List your corridors`GET /api/partner/v1/corridors`	`200` `401` `403` `429`
Price a transfer`POST /api/partner/v1/quote`	`200` `400` `401` `403` `429` `503`
Validate payout fields`POST /api/partner/v1/beneficiaries/validate`	`200` `400` `401` `403` `422` `429`
Store a beneficiary`POST /api/partner/v1/beneficiaries`	`201` `400` `401` `403` `422` `429`
Mint a transfer`POST /api/partner/v1/transactions`	`200` `201` `400` `401` `403` `404` `409` `422` `429` `503`
List your transfers`GET /api/partner/v1/transactions`	`200` `401` `403` `429`
Fetch one transfer`GET /api/partner/v1/transactions/{id}`	`200` `401` `403` `404` `429`
Confirm funds captured`POST /api/partner/v1/transactions/{id}/confirm`	`200` `401` `403` `404` `409` `422` `429`
Push one corridor rate`PUT /api/partner/v1/rates`	`200` `400` `401` `403` `429`
Your rate sheet`GET /api/partner/v1/rates`	`200` `401` `403` `429`
Settlements statement`GET /api/partner/v1/settlements`	`200` `400` `401` `403` `429`