Error management - HUB2 Documentation

Error format

Errors returned by the HUB2 API use the following format (some compliance endpoints return statusCode, message and error for 404 responses). 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"
}

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.
`missing_permission`	The API key does not have the permission required by the endpoint (HTTP `403`).
`wrong_provider`	The provider does not exist for the country and payment method of the request (HTTP `400`). Use `GET /data/providers` to list the valid providers.
`instant_payment_not_enabled_for_merchant`	Instant payment is not enabled for the merchant (HTTP `403`). Contact HUB2 Support.
`instant_payment_live_only`	Instant payment aliases are managed in live mode only (HTTP `403`).
`instant_payment_alias_not_owned`	The instant payment alias does not exist or is not registered to the merchant (HTTP `403`).
`instant_payment_account_not_enrolled`	The account is not enrolled for instant payment yet (HTTP `409`). Contact HUB2 Support.
`instant_payment_primary_alias_protected`	The alias is the primary alias registered by HUB2 and cannot be deleted through the API (HTTP `409`).
`instant_payment_alias_deactivated`	HUB2 deactivated the alias of the account. Only HUB2 Support can restore it (HTTP `409`).
`instant_payment_alias_refused`	The instant payment directory refused the alias operation. Nothing was changed (HTTP `422`).
`instant_payment_account_missing`	The merchant has no live account of the requested type (HTTP `422`).
`instant_payment_participant_not_served`	Instant payment is not available in the merchant’s country (HTTP `422`).
`instant_payment_alias_not_recorded`	The alias was registered in the directory but HUB2 could not record it. Retry the request (HTTP `502`).
`instant_payment_alias_deletion_not_recorded`	The alias was removed from the directory but HUB2 could not record the removal. Retry the request (HTTP `502`).
`instant_payment_alias_divergence`	The directory and HUB2 disagree about the alias. Nothing was recorded. Contact HUB2 Support (HTTP `502`).
`instant_payment_alias_rail_unavailable`	The instant payment directory is unavailable. Retry later (HTTP `503`).
`reference_required`	The payout `reference` is blank, meaning empty or only spaces (HTTP `400`). Applies when duplicate protection is enabled on your account.
`duplicate_reference`	The `reference` is already used by a payout with different details (HTTP `409`). Use a new reference, or resend the original payout to get it back. Applies when duplicate protection is enabled on your account.
`possible_duplicate`	A payout with the same details was created under another reference less than 15 minutes ago, so this one was not created (HTTP `409`). The error body also carries `rejection_id` and `expires_at`, described below. Applies when duplicate protection is enabled on your account.
`invalid_duplicate_confirmation`	The `rejectionId` sent cannot confirm this payout: it is unknown, expired or already used, or the payout differs from the refused one (HTTP `422`). Resend the payout without `rejectionId`. Applies when duplicate protection is enabled on your account.

Extra fields of `possible_duplicate`

The body of a possible_duplicate error carries two fields in addition to the usual format:

Field name	Description
`rejection_id`	Identifier to send back as `rejectionId`, with the payout unchanged, to confirm that the payout is intended.
`expires_at`	Until when `rejection_id` can be used, in ISO 8601 format (15 minutes after the refusal).

Duplicate protection is not enabled by default: contact HUB2 Support to enable it. See Retrying a payout safely.

​Error format

​Example: error 404

​Error codes

​HTTP status codes

​Application error codes

​Extra fields of possible_duplicate

Error format

Example: error 404

Error codes

HTTP status codes

Application error codes

Extra fields of `possible_duplicate`