Error and Warning Dictionary

The BEEM API responds with detailed information in the event of a failed request. Below is a comprehensive list of payment error codes, along with brief descriptions on how to address them. This resource serves as a valuable reference for developers, enabling them to efficiently troubleshoot and address errors in their applications' integration with BEEMs API.

1000-1999

These errors are returned in the format below:

{
    "code": "MER-PAY-XXXX",
    "status": "Forbidden",
    "message": <error message>,
    "documentLink": ""
}

ERROR CODE

Code	Message	Description
MER-PAY-1000	Not authorised to perform this action	Error given when a payment was attempted using API keys that did not have withdrawals enabled, or was requested from a non-whitelisted IP. New keys are needed with the relevant permissions.

2000-2999

🚧
Should you encounter any of the errors outlined in this section, be aware that your payment or transaction attempt will not be successful. The system will reject the transaction at the API level, consequently preventing the creation of a failed transaction record. Therefore, you will not find any evidence of the unsuccessful operation within the merchant portal.

These errors are returned in the format below:

{
  “errorList”:
    [
      {
        “code”: "MER-PAY-XXXX",
        “parameter”: <parameter causing error>,
        “message”: <error message>
      }
    ]
}

ERROR CODE

Code	Message	Description
layer1:payment:checkout:2000	invalid parameter value	Error given when a payment was attempted using one or more parameters with the incorrect format. Parameter to change is given in the parameter field.
layer1:payment:checkout:2001	amount x.xx <currency> failed is less than minimum limit of x.xx <currency>	Error given when a payment was below the minimum threshold amount set for the account, the payment amount needs to be increased.
layer1:payment:checkout:2001	amount x.xx <currency> failed validation as it is over max limit x.xx <currency>	Error given when a payment was above the maximum threshold amount set for the account, the payment amount needs to be decreased.
layer1:payment:checkout:2004	payment has expired	Error given when a quote that is accepted by an end customer has expired. A new quote needs to be issued.
layer1:payment:checkout:2005	address <address> has failed validation for currency: <currency>, protocol: <protocol> and tag: <tag>	Error given when a supplied wallet address fails validation. Could be due to wrong address format or providing the incorrect protocol, ie issuing a TRC20 payment to an ERC20 address.
layer1:payment:checkout:2006	merchant not found	Error given when the Merchant ID given in the payment request cannot be found on the account.
layer1:payment:checkout:2008	payment with external id <id> could not be found	Error given when the payment ID could not be found.
layer1:payment:checkout:2009	invalid request message	Error given when the JSON payload of a request is not valid syntax.
layer1:payment:checkout:2010	<reference> value already exists	Error given when a payment was already created using this reference. All references need to be unique.
layer1:payment:checkout:2011	currency <currency> is disabled	Error given when creating a payment with a currency that is disabled and is not available for trade.
layer1:payment:checkout:2012	insufficient funds.	Error given when there is too little funds in the associated wallet to allow for the withdrawal.
layer1:payment:checkout:2013	finalised quote	Error given when the quote has already been finalised and cannot be updated or modified.
layer1:payment:checkout:2014	expired quote	Error given when the quote has expired and cannot be used for transactions.
layer1:payment:checkout:2015	crypto instruction not found for payment <id>	Error given when the crypto payout instructions are not present on a payout.
layer1:payment:checkout:2016	merchant not authorised to perform this action	Error given when a merchant is not authorised to perform the requested action.
layer1:payment:checkout:2017	not eligible for the requested action	Error given when the merchant or payment is not eligible for the requested operation.
layer1:payment:checkout:2018	optimistic locking failed	Error given when a concurrent update occurs and the data has changed since it was last read.
layer1:payment:checkout:2019	invalid currency	Error given when the provided currency is invalid or not supported.
layer1:payment:checkout:2020	payment limit not found	Error given when the account's payment limit information is not available.
layer1:payment:checkout:2021	currency limit not found	Error given when the system cannot find the limit associated with the provided currency.
layer1:payment:checkout:2022	account dust value not found	Error given when the minimum dust value for the account currency is missing.
layer1:payment:checkout:2023	system dust value exception	Error given when the system does not support the given dust value for the currency.
layer1:payment:checkout:2024	invalid protocol	Error given when the provided protocol is not valid for the currency.
layer1:payment:checkout:2025	invalid refund address	Error given when the refund address provided is invalid.
layer1:payment:checkout:2026	gateway transaction not found	Error given when the gateway cannot find the specified transaction.
layer1:payment:checkout:2027	address validation failed	Error given when the crypto payout receive address format is invalid.
layer1:payment:checkout:2028	address screening failed	Error given when the address fails financial crime screening.
layer1:payment:checkout:2029	protocol not found	Error given when the requested protocol is not found in the system.
layer1:payment:checkout:2030	currency protocol not found	Error given when the specified currency protocol is not found in the system.
layer1:payment:checkout:2031	account not enabled for flow	Error given when the account is not configured to support the requested flow.
layer1:payment:checkout:2032	customer ID required	Error given when the customer ID is required for the payroll flow but is missing.
layer1:payment:checkout:2033	multiple protocols for currency	Error given when multiple protocols are associated with a single currency, causing ambiguity.
layer1:payment:checkout:2034	mass payout file upload error	Error given when there is an issue with the uploaded mass payout file.
layer1:payment:checkout:2035	mass payout data row error	Error given when there is an issue with a specific row in the mass payout data.
layer1:payment:checkout:2036	mass payout max rows exceeded	Error given when the number of rows in a mass payout exceeds the allowed limit.
layer1:payment:checkout:2037	duplicate payout file name	Error given when a mass payout file with a duplicate name is uploaded.
layer1:payment:checkout:2038	missing payout file	Error given when a required mass payout file is missing.
layer1:payment:checkout:2039	missing merchant or wallet ID	Error given when both merchant ID and wallet ID are missing for a mass payout.
layer1:payment:checkout:2040	bad payout file header	Error given when the header of the mass payout file is incorrect.
layer1:payment:checkout:2041	mass payout item deletion error	Error given when a specific item in a mass payout cannot be deleted.
layer1:payment:checkout:2042	mass payout item edit error	Error given when a specific item in a mass payout cannot be edited.
layer1:payment:checkout:2043	missing merchant ID or wallet ID	Error given when either the merchant ID or wallet ID is missing.