Error Responses

All errors returned by the API follow a consistent JSON format:

{
  "status": "error",
  "error": {
    "code": <integer>,
    "message": <string>,
    "details": <list>
  }
}

details is an empty list for most errors. When a specific field caused the failure, it holds objects of the form {"field": <string>, "error": <string>}.

Error Codes

Code	HTTP	Message	Cause
1004	400	Invalid input data	Body failed validation
1005	400	Invalid channel	Channel does not belong to the API key
2001	400	Invalid JSON payload	Body is not valid JSON
2002	400	Missing parameter	A required query parameter is absent
2006	400	Bad Request	Transaction is not in a state that allows the action
1001	401	Missing API key	X-API-Key header absent
1002	401	Missing signature	X-Signature header absent
1003	401	Invalid signature	Signature does not match the signed message
1010	401	Invalid timestamp header	X-Timestamp absent, unparsable, or older than 10 min
2004	403	Permission denied	IP not on the allow list, or access denied
1006	404	Not found	Transaction or resource does not exist
1007	404	Please contact support for further action.	No gateway available for this method/currency
1009	409	Insufficient balance	Channel balance too low for the payout
1000	500	Internal server error	Unexpected runtime error

400 Bad Request

• Invalid input → request body fails validation
• Malformed JSON → body is not valid JSON
• Missing parameter → required query parameter not provided

Example:

{
  "status": "error",
  "error": {
    "code": 2002,
    "message": "Missing parameter",
    "details": []
  }
}

An unsupported payment method type is reported as invalid input, with the offending field named in details:

{
  "status": "error",
  "error": {
    "code": 1004,
    "message": "Invalid input data",
    "details": [
      {"field": "payment_method.type", "error": "Unsupported payment method type"}
    ]
  }
}

401 Unauthorized

• Missing API key
• Missing signature
• Invalid signature
• Invalid timestamp header

Example:

{
  "status": "error",
  "error": {
    "code": 1003,
    "message": "Invalid signature",
    "details": []
  }
}

403 Forbidden

• Permission denied → client does not have rights to access resource, or the request came from an address outside the account's IP allow list

Example:

{
  "status": "error",
  "error": {
    "code": 2004,
    "message": "Permission denied",
    "details": []
  }
}

404 Not Found

• Not found → transaction, reference or resource does not exist
• Gateway not found → no gateway is available for the requested method

Example:

{
  "status": "error",
  "error": {
    "code": 1006,
    "message": "Not found",
    "details": []
  }
}

409 Conflict

• Insufficient balance → the channel does not hold enough funds for the payout

Example:

{
  "status": "error",
  "error": {
    "code": 1009,
    "message": "Insufficient balance",
    "details": []
  }
}

---

500 Internal Server Error

• Unexpected runtime error
• Invalid response from service

{
  "status": "error",
  "error": {
    "code": 1000,
    "message": "Internal server error",
    "details": []
  }
}

---

Declined Transactions

A declined payment or payout is not an API error: the endpoint answers with a success code and the transaction carries status: "failed" together with error_code and error_message.

error_code	error_message
DECLINED_GENERIC	The payment/payout was declined.
PERSONAL_DATA_NOT_PROVIDED	Personal data was not provided.
CARD_DATA_NOT_PROVIDED	Card data was not provided.
BROWSER_DATA_NOT_PROVIDED	Browser data was not provided.
DECLINED_3DS_AUTHENTICATION_FAILED	3-D Secure authentication failed.
PROVIDER_PROCESSING_FAILED	Payment provider returned an error.
INSUFFICIENT_BALANCE	Insufficient balance for payout.
VALIDATION_ERROR	—