Skip to main content

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​

CodeHTTPWhat to do
MERCHANT_INACTIVE403The merchant account is blocked or deactivated. Contact support.
HTTPCodeCauseWhat to do
401AUTH_HEADERS_MISSINGA signature header is absent.Send all four X-Gate-* headers.
401AUTH_TIMESTAMP_INVALIDX-Gate-Ts is not an integer.Send unix seconds.
401AUTH_TIMESTAMP_SKEWThe timestamp is more than 300 seconds off.Sync the clock.
401AUTH_NONCE_INVALIDThe nonce is not 8 to 128 characters.Use 16 hex characters.
401AUTH_FAILEDUnknown key or wrong signature.See Authentication.
409REPLAY_DETECTEDThe nonce was already used within the window.Fresh nonce per request.

Creating an order​

CodeHTTPWhat to do
ORDER_REF_INVALID400orderRef is longer than 255 characters.
BANK_REQUIRED400A Monobank cash desk needs targetBank, the bank the customer pays from.
BANK_UNKNOWN400targetBank names no bank we know. Use a key from GET /gw/v1/banks.
ORDER_REF_CONFLICT409The same orderRef already names an order with a different amount or currency. Use a new reference.
ORDER_IN_PROGRESS409An earlier call with the same orderRef is still creating its order. Retry in a few seconds, or fetch the order by its orderRef.
HTTPCodeCauseWhat to do
400AMOUNT_INVALIDamount is zero or negative.Send a positive amount.
400LIFETIME_INVALIDlifetimeMinutes is outside 1 to 1440.Fix or omit it.
400RECEIPT_*The receipt file was refused: missing name or content, bad base64, unsupported type, content not matching the extension, empty, over 10 MB. Nothing was stored: no order created, no receipt added.Fix the file and repeat; see receipt files.
400MERCHANT_INACTIVEThe account is inactive or blocked.Contact support.
400SHOP_INACTIVEYou disabled the cash desk.Enable it in the cabinet.
400SHOP_STOPPEDThe platform stopped the cash desk; detail carries the reason.Contact support.
400CALLBACK_URL_REQUIREDNeither the order nor the cash desk has a callback URL.Set one.
400INVALID_CALLBACK_URLThe URL is relative, not http(s), or points to a private or internal host.Use a public https:// address.
400RAIL_REQUIREDThe cash desk allows several rails and none was passed.Pass rail.
400INVALID_RAILrail is not Sbp, C2c or Phone.Fix the value.
400RAIL_NOT_ENABLEDThe rail is not allowed on this cash desk.Pass an allowed one, or change the cash desk.
400INVALID_CURRENCYThe code is unknown or disabled on the platform.Check GET /gw/v1/rates.
400CURRENCY_NOT_PAYABLEThe currency has no rate source.Use another currency.
400CURRENCY_NOT_ENABLEDThe currency is not allowed on this cash desk.Add it to the cash desk.
400FX_RATE_UNAVAILABLENo rate could be obtained right now.Retry in a minute.
400AMOUNT_BELOW_MINBelow the cash desk minimum; detail shows it in USD.Raise the amount or the limit.
400AMOUNT_ABOVE_MAXAbove the cash desk maximum.Lower the amount or raise the limit.
400TRAFFIC_LIMIT_REACHEDA turnover cap is reached; detail names the scope and window.Wait for the window, or contact support.
400MERCHANT_NOT_APPROVEDThe account is under review and the sandbox is off.Wait for approval.
503NO_AVAILABLE_METHODNo provider accepted the order.Retry later with a back-off.
404SHOP_NOT_FOUNDThe cash desk behind the key no longer exists.Contact support.

Fetching and cancelling​

CodeHTTPWhat to do
ORDER_AWAITING_CONFIRMATION409The provider reported the payment and the platform is confirming it. Do not cancel; wait for the callback.
ORDER_IN_DISPUTE409An appeal is open on the order. It closes when the appeal is decided.
HTTPCodeCause
404ORDER_NOT_FOUNDNo such order on this cash desk, by id or by reference.
409ORDER_ALREADY_COMPLETEDA paid order cannot be cancelled, appealed or take a receipt.
409RECEIPT_LIMITThe order already holds as many receipts as it can take; the reviewer has them.

Appeals​

CodeHTTPWhat to do
ORDER_STILL_OPEN409The order has not closed yet. Send the receipt to the order with POST /gw/v1/orders/{id}/receipts: the appeal opens by itself if it closes without a credit.
HTTPCodeCause
400ORDER_REQUIREDorderId is missing.
404ORDER_NOT_FOUNDNo such order on this cash desk.
404APPEAL_NOT_FOUNDNo such appeal on this cash desk.
409ORDER_ALREADY_COMPLETEDThe order is already credited; there is nothing to appeal.
409APPEAL_REJECTEDThe appeal could not be opened for another reason; detail says why.

Everything else​

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

Retry guidance​

CodeSafe to retry the same request?
FX_RATE_UNAVAILABLE, NO_AVAILABLE_METHOD, 5xx, 429Yes, with a back-off and the same orderRef.
TRAFFIC_LIMIT_REACHEDYes, after the window rolls over.
REPLAY_DETECTEDYes, with a new nonce.
Any other 4xxNo. Fix the request or the configuration first.