​
Error format

The error format in HUB2 API is being standardized. Below are the fields in the standardized response along with an example:
Field nameDescription
statusThe HTTP status
codeA business error code internal to hub2 api (see full list below)
messageA readable description of the error code
request_idUnique request identifier
Currently, it is necessary to set the header ‘x-use-standardized-error’ === true to obtain this standardized format.
Starting from October the 1st of 2024, this error format will be the only one returned by the HUB2 API. Therefore, merchants needs to update their integration before this deadline.

​
Sample : Error 404

{
    "status": 404,
    "code": "Not Found",
    "message": "Country not found",
    "request_id": "req_RRg_xtA55q32PLIWYVLFL"
}
Note: the field request_id is a unique request identifier that will allow HUB2 Support team to respond more quickly in case of help requests.

​
Error codes

​
HTTP status codes

HTTP status codes do not indicate application errors.
Standard HTTP status codes that can be returned by the HUB2 API :
Status CodeStatus TextDescription
200OKThe HTTP request was completed as expected.
400Bad RequestThe request was unacceptable, often due to a missing required parameter.
401UnauthorizedNo valid API key provided.
402Request FailedThe parameters were valid but the request failed.
403ForbiddenThe API key doesn’t have permissions to perform the request.
404Not FoundThe requested resource doesn’t exist.
409ConflictThe client’s request is in direct conflict with another action that is already in progress or has been completed
429Too Many RequestsExcessive requests have been made to the API in a short amount of time. The request wasn’t accepted to preserve overall api performance
500, 502, 503, 504Server-related errorsSomething went wrong on HUB2’s end.

​
Application error codes

Application error codes that may be returned by the HUB2 API :
CodeReason
account-already-existsAn account ‘accountType’ in mode (live or sandbox) already exists for the merchant merchantId
cancellation-already-doneThe transaction id has already been canceled.
insufficient-fundsThe account does not have enough funds to transfer amount currency.
invalid-currencyInvalid currency (currency).
locked-accountThe account is locked.
transaction-not-foundThe transaction transactionId for the account accountId is not found.
currency-not-foundCurrency not found (currency).
withdrawal-unavailableWithdrawals are unavailable on the account accountId. The account may be blocked or does not have sufficient funds.
missing-funds-reservationInsufficient reserved funds.
merchant-not-foundThe merchant is not found.
unsupported-commandUnsupported command.
no_auth_requiredThe transaction id does not require authentication.
transaction_canceledThe transaction (payment) has been canceled. No payment can be processed.
transaction_missingThe transaction (transfer or payment) is not found.
transaction_in_progressThe transaction (transfer or payment) is already in progress.
transaction_doneThe transaction (transfer or payment) has already been completed.