Error management - HUB2 Documentation

Error format

The error format in HUB2 API is being standardized. Below are the fields in the standardized response along with an example:

Field name	Description
`status`	The HTTP status
`code`	A business error code internal to HUB2 API (see full list below)
`message`	A readable description of the error code
`request_id`	Unique 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 Code	Status Text	Description
`200`	`OK`	The HTTP request was completed as expected.
`400`	`Bad Request`	The request was unacceptable, often due to a missing required parameter.
`401`	`Unauthorized`	No valid API key provided.
`402`	`Request Failed`	The parameters were valid but the request failed.
`403`	`Forbidden`	The API key doesn’t have permissions to perform the request.
`404`	`Not Found`	The requested resource doesn’t exist.
`409`	`Conflict`	The client’s request is in direct conflict with another action that is already in progress or has been completed
`429`	`Too Many Requests`	Excessive 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`, `504`	Server-related errors	Something went wrong on HUB2’s end.

Application error codes

Application error codes that may be returned by the HUB2 API :

Code	Reason
`account-already-exists`	An account ‘accountType’ in mode (live or sandbox) already exists for the merchant merchantId
`cancellation-already-done`	The transaction id has already been canceled.
`insufficient-funds`	The account does not have enough funds to transfer amount currency.
`invalid-currency`	Invalid currency (currency).
`locked-account`	The account is locked.
`transaction-not-found`	The transaction transactionId for the account accountId is not found.
`currency-not-found`	Currency not found (currency).
`withdrawal-unavailable`	Withdrawals are unavailable on the account accountId. The account may be blocked or does not have sufficient funds.
`missing-funds-reservation`	Insufficient reserved funds.
`merchant-not-found`	The merchant is not found.
`unsupported-command`	Unsupported command.
`no_auth_required`	The transaction id does not require authentication.
`transaction_canceled`	The transaction (payment) has been canceled. No payment can be processed.
`transaction_missing`	The transaction (transfer or payment) is not found.
`transaction_in_progress`	The transaction (transfer or payment) is already in progress.
`transaction_done`	The transaction (transfer or payment) has already been completed.

​Error format

​Sample : Error 404

​Error codes

​HTTP status codes

​Application error codes

Error format

Sample : Error 404

Error codes

HTTP status codes

Application error codes