Errors

Every fault answers with the same envelope, described in Responses. Branch on fault.code; fault.detail may include values and may change wording.

Signature

Code	HTTP	What to do
MERCHANT_INACTIVE	403	The merchant account is blocked or deactivated. Contact support.

HTTP	Code	Cause	What to do
401	AUTH_HEADERS_MISSING	A signature header is absent.	Send all four X-Gate-* headers.
401	AUTH_TIMESTAMP_INVALID	X-Gate-Ts is not an integer.	Send unix seconds.
401	AUTH_TIMESTAMP_SKEW	The timestamp is more than 300 seconds off.	Sync the clock.
401	AUTH_NONCE_INVALID	The nonce is not 8 to 128 characters.	Use 16 hex characters.
401	AUTH_FAILED	Unknown key or wrong signature.	See Authentication.
409	REPLAY_DETECTED	The nonce was already used within the window.	Fresh nonce per request.

Creating an order

Code	HTTP	What to do
ORDER_REF_INVALID	400	orderRef is longer than 255 characters.
ORDER_REF_CONFLICT	409	The same orderRef already names an order with a different amount or currency. Use a new reference.

HTTP	Code	Cause	What to do
400	AMOUNT_INVALID	amount is zero or negative.	Send a positive amount.
400	LIFETIME_INVALID	lifetimeMinutes is outside 1 to 1440.	Fix or omit it.
400	MERCHANT_INACTIVE	The account is inactive or blocked.	Contact support.
400	SHOP_INACTIVE	You disabled the cash desk.	Enable it in the cabinet.
400	SHOP_STOPPED	The platform stopped the cash desk; detail carries the reason.	Contact support.
400	CALLBACK_URL_REQUIRED	Neither the order nor the cash desk has a callback URL.	Set one.
400	INVALID_CALLBACK_URL	The URL is relative, not http(s), or points to a private or internal host.	Use a public https:// address.
400	RAIL_REQUIRED	The cash desk allows several rails and none was passed.	Pass rail.
400	INVALID_RAIL	rail is not Sbp, C2c or Phone.	Fix the value.
400	RAIL_NOT_ENABLED	The rail is not allowed on this cash desk.	Pass an allowed one, or change the cash desk.
400	INVALID_CURRENCY	The code is unknown or disabled on the platform.	Check GET /gw/v1/rates.
400	CURRENCY_NOT_PAYABLE	The currency has no rate source.	Use another currency.
400	CURRENCY_NOT_ENABLED	The currency is not allowed on this cash desk.	Add it to the cash desk.
400	FX_RATE_UNAVAILABLE	No rate could be obtained right now.	Retry in a minute.
400	AMOUNT_BELOW_MIN	Below the cash desk minimum; detail shows it in USD.	Raise the amount or the limit.
400	AMOUNT_ABOVE_MAX	Above the cash desk maximum.	Lower the amount or raise the limit.
400	TRAFFIC_LIMIT_REACHED	A turnover cap is reached; detail names the scope and window.	Wait for the window, or contact support.
400	MERCHANT_NOT_APPROVED	The account is under review and the sandbox is off.	Wait for approval.
503	NO_AVAILABLE_METHOD	No provider accepted the order.	Retry later with a back-off.
404	SHOP_NOT_FOUND	The cash desk behind the key no longer exists.	Contact support.

Fetching and cancelling

Code	HTTP	What to do
ORDER_AWAITING_CONFIRMATION	409	The provider reported the payment and the platform is confirming it. Do not cancel; wait for the callback.
ORDER_IN_DISPUTE	409	An appeal is open on the order. It closes when the appeal is decided.

HTTP	Code	Cause
404	ORDER_NOT_FOUND	No such order on this cash desk, by id or by reference.
409	ORDER_ALREADY_COMPLETED	A paid order cannot be cancelled or appealed.

Appeals

Code	HTTP	What to do
ORDER_STILL_OPEN	409	The order has not closed yet. Wait for expiry or cancel it, then appeal.

HTTP	Code	Cause
400	ORDER_REQUIRED	orderId is missing.
404	ORDER_NOT_FOUND	No such order on this cash desk.
404	APPEAL_NOT_FOUND	No such appeal on this cash desk.
409	ORDER_ALREADY_COMPLETED	The order is already credited; there is nothing to appeal.
409	APPEAL_REJECTED	The appeal could not be opened for another reason; detail says why.

Everything else

HTTP	Meaning	What to do
429	Rate limited; the body is empty.	Back off for the window.
5xx	Our side failed.	Retry with a back-off; send the traceId to support if it persists.

Retry guidance

Code	Safe to retry the same request?
FX_RATE_UNAVAILABLE, NO_AVAILABLE_METHOD, 5xx, 429	Yes, with a back-off and the same orderRef.
TRAFFIC_LIMIT_REACHED	Yes, after the window rolls over.
REPLAY_DETECTED	Yes, with a new nonce.
Any other 4xx	No. Fix the request or the configuration first.