Error management - HUB2 Documentation

Error format

Every error returned by the HUB2 API uses the following format. Requests rejected by the web application firewall return a 403 with an HTML body instead (see Security).

Field name	Description
`status`	The HTTP status code
`code`	A business error code defined by the HUB2 API (see the list below)
`message`	A readable description of the error
`request_id`	Unique request identifier

Example: error 404

{
    "status": 404,
    "code": "Not Found",
    "message": "Country not found",
    "request_id": "req_RRg_xtA55q32PLIWYVLFL"
}

Note: include the request_id value when contacting HUB2 Support; it allows the team to find your request and respond faster.

Error codes

HTTP status codes

HTTP status codes do not indicate application errors.

Standard HTTP status codes that the HUB2 API can return:

Status code	Status text	Description
`200`	`OK`	The request was completed as expected.
`201`	`Created`	The resource was created.
`202`	`Accepted`	The request was accepted for asynchronous processing.
`400`	`Bad Request`	The request was unacceptable, often due to a missing or invalid parameter.
`401`	`Unauthorized`	No valid API key was provided.
`403`	`Forbidden`	The API key does not have the permissions to perform the request.
`404`	`Not Found`	The requested resource does not exist.
`409`	`Conflict`	The request conflicts with another action that is already in progress or has been completed.
`422`	`Unprocessable Entity`	The parameters were valid, but the request could not be processed.
`429`	`Too Many Requests`	Too many requests were sent in a short amount of time. The request was rejected to preserve overall API performance. See Rate limits.
`500`, `501`, `502`, `503`, `504`	Server errors	Something went wrong on HUB2’s end.

Application error codes

Application error codes that the HUB2 API may return:

Code	Reason
`account-already-exists`	An account of this type already exists for the merchant in this mode (live or sandbox).
`cancellation-already-done`	The transaction has already been canceled.
`insufficient-funds`	The account does not have enough funds to transfer the requested amount.
`invalid-currency`	The currency is invalid.
`locked-account`	The account is locked.
`transaction-not-found`	The transaction was not found for this account.
`currency-not-found`	The currency was not found.
`withdrawal-unavailable`	Withdrawals are unavailable on the account. The account may be blocked or may not have sufficient funds.
`missing-funds-reservation`	Insufficient reserved funds.
`merchant-not-found`	The merchant was not found.
`unsupported-command`	Unsupported command.
`no_auth_required`	The payment intent does not require authentication.
`transaction_canceled`	The payment intent has been canceled. No payment can be processed.
`transaction_missing`	The transaction (transfer or payment) was 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

​Example: error 404

​Error codes

​HTTP status codes

​Application error codes

Error format

Example: error 404

Error codes

HTTP status codes

Application error codes