Error Handling
Error Response Structure
{
"id": "E001",
"code": "SOMETHING_WENT_WRONG",
"message": "Something went wrong. We're working on it",
"requestId": "req_12345",
"debugMessage": "No resource found with the given ID",
"subErrors": [
{
"fieldName": "resourceId",
"message": "Resource ID is invalid",
"debugMessage": "Resource ID 404 not found in the database"
}
]
}
Response Fields
| Field | Description |
|---|---|
id | Stable, granular identifier such as E160. Branch integration logic on this value. It is null for generic request-body validation failures; use code and subErrors[].fieldName in that case. |
code | Coarse category shared by many IDs. Do not use it to distinguish specific error conditions. Values include SOMETHING_WENT_WRONG, RESOURCE_NOT_FOUND, INPUT_INVALID, OPERATION_NOT_ALLOWED, UNDEFINED_STATE, EXTERNAL_FAILURE, DATA_VALIDATION_ERROR, and AUTHENTICATION_FAILED. |
message | Human-readable description. It is not guaranteed to be safe for display to end users. |
requestId | Correlation ID. Include it when contacting Hubble support. |
debugMessage | Internal debugging context. Empty in production. |
subErrors | Field-level details, mainly populated for input-validation failures. |
HTTP Status Codes
HTTP status reflects the failure category, not a fixed mapping for each error ID. Do not rely on status alone to distinguish errors.
| Status | Meaning |
|---|---|
400 | Nearly all partner-facing business errors (E1xx–E4xx below), except E301 |
401 | Authentication failure, such as a bad or expired token |
404 | Resource not found; returned with id: E001 when no more specific descriptor exists |
500 | Unexpected/internal failures and E301 wallet inconsistency |
E001 is not a business error. It is used when no specific descriptor is available, including unhandled 500 and 404 responses. Treat it as an uncategorized failure, not as a specific condition to branch on.
The following is the complete authoritative list of error IDs returned by the API.
Brand Errors
| Code | Message | Retryable |
|---|---|---|
E100 | Brand is temporarily disabled owing to failures | Yes, after a short wait |
E101 | Brand is not enabled for you, please contact support | No |
E102 | Brand is not active | No |
E103 | Brand is not available for this business model | No |
Order Validation Errors
| Code | Message | Retryable |
|---|---|---|
E150 | This denomination is not available for this brand | No; fix the request |
E151 | Order amount doesn't match the denomination amount | No; fix the request |
E152 | Maximum denomination limit exceeded | No; fix the request |
E153 | Maximum number of denominations exceeded | No; fix the request |
E154 | Maximum number of vouchers per denomination exceeded | No; fix the request |
E155 | Please enter amount between &1 and &2 | No; fix the request |
E156 | Max voucher count per order exceeded | No; fix the request |
E157 | Invalid denominations sent | No; fix the request |
E158 | Denomination is out of stock | No; try a different denomination |
E159 | Only single denomination allowed per order | No; fix the request |
E160 | Order already exists for reference id | No; see referenceId reuse |
E161 | Discount amount cannot be greater than order amount | No; fix the request |
E162 | Reference ID must be less than 40 characters | No; fix the request |
E163 | Denomination details are required for this brand | No; fix the request |
E164 | Quantity allowed per denomination is: &1 | No; fix the request |
E165 | Invalid quantity requested | No; fix the request |
E166 | Invalid request sent to provider, please verify and retry | Fix the request, then retry with a new referenceId |
Voucher Generation Errors
| Code | Message | Retryable |
|---|---|---|
E200 | Voucher generation failed, please contact support | The order is terminal and its wallet debit is automatically reversed. Retry with a new referenceId; contact support if it persists. |
E201 | Provider polling failed, please contact support | Yes; retry with a new referenceId after a short wait |
E202 | Order cancellation failed, order is already in terminal state | No |
E203 | Order cancellation failed, order cant be cancelled before cutoff time | No |
E204 | Voucher generation is temporarily unavailable, please try again later | Yes; retry with a new referenceId after a short wait |
Order Cancellation Is Restricted
The cancel-order endpoint associated with E202 and E203 is not a general partner capability. It is enabled only for specific integrations. If it is not enabled for your account, calling it returns E303 (This feature is not available). Contact your Hubble account manager if you need cancellation support.
Partner Errors
| Code | Message | Retryable |
|---|---|---|
E300 | Insufficient wallet balance | No; top up your wallet |
E301 | Wallet balance is inconsistent, please contact admin | No; contact Hubble support |
E302 | This resource is not available | No |
E303 | This feature is not available | No |
E304 | This resource already exists | No |
E305 | Delivery details are not available for this order | No |
E306 | No vouchers are available for this order | No |
E307 | Voucher communication is not configured for you, please contact support | No; contact Hubble support |
Limit Errors
| Code | Message | Retryable |
|---|---|---|
E400 | Brand is temporarily unavailable, please try again later | Yes, after a short wait |
Retrying Safely
Only E100, E201, E204, E400, and generic 5xx or network-level failures are transient and safe to retry. Everything else is either a request problem that must be fixed or a terminal business state.
When retrying an order after it was created, use a new referenceId. The only case where the same referenceId is safe is when the Place Order request timed out and a lookup confirms that no order was created.
referenceId Reuse After a FAILED Order
If an order reaches FAILED, its wallet debit is automatically reversed, but its referenceId remains consumed. Calling Place Order with that same referenceId returns E160. Generate a new one for every retry attempt.
Voucher Refunds and Reversals
CANCELLED and REVERSED are system-driven order statuses, not states that partners generally trigger through the API. If a voucher needs to be refunded or reversed outside the automatic wallet reversal for a failed order, contact Hubble support.
Troubleshooting with Support
Provide the X-REQUEST-ID, full error response, timestamp, order or reference ID, and request payload with sensitive credentials removed. Retaining these details for every API call significantly speeds up investigation.