Error Handling

Understanding error responses and codes for proper error handling in your integration.

---

Error Response Structure

All API errors follow a consistent structure:

{
  "id": "E001",
  "code": "RESOURCE_NOT_FOUND",
  "message": "Requested resource is not found",
  "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	Error code identifier (e.g., E100, E200)
code	Machine-readable error code
message	Human-readable error message
requestId	Request identifier for troubleshooting
debugMessage	Additional debug information
subErrors	Array of field-level errors (for validation errors)

---

Error Codes

Brand Errors

Code	Description	Resolution
E100	Brand is temporarily disabled owing to failures	Provider failure. Wait and retry later.
E101	Brand is not enabled for you	Contact Hubble support to enable this brand for your account.
E102	Brand is not active	Brand is INACTIVE. Do not display to users. Check catalog for updated status.

Order Validation Errors

Code	Description	Resolution
E150	This denomination is not available for this brand	Refresh your catalog. Only use denominations in amountRestrictions.denominations.
E151	Order amount doesn't match the denomination amount	Ensure amount = sum of (denomination × quantity).
E152	Maximum denomination limit exceeded	Reduce the denomination amount.
E153	Maximum number of denominations exceeded	Reduce the number of distinct denominations in denominationDetails.
E154	Maximum number of vouchers per denomination exceeded	Check maxVouchersPerDenomination in brand's amountRestrictions.
E155	Voucher amount not within the allowed range	For FLEXIBLE brands, ensure amount is between minVoucherAmount and maxVoucherAmount.
E156	Max voucher count per order exceeded	Check maxVouchersPerOrder in brand's amountRestrictions.
E157	Invalid denominations sent	Validate denominations against brand's catalog before ordering.
E158	Denomination is out of stock	Try a different denomination or brand.
E159	Only single denomination allowed per order	Some brands allow only one denomination type per order.
E160	Order already exists for reference id	The referenceId has been used. Generate a new unique referenceId.

Voucher Generation Errors

Code	Description	Resolution
E200	Voucher generation failed	Provider-side failure. Retry after 1–2 minutes. If persistent, contact Hubble support with X-REQUEST-ID.
E201	Provider polling failed	Same resolution as E200.
E202	Order cancellation failed, order is already in terminal state	Order has already completed (SUCCESS or FAILED). Cannot cancel.
E203	Order cancellation failed, order can't be cancelled before cutoff time	Wait for cutoff time or contact support.

Partner Errors

Code	Description	Resolution
E300	Insufficient wallet balance	Top up your wallet before retrying. Set up Wallet Low Balance webhook for alerts.
E301	Wallet balance is inconsistent	Contact Hubble admin to resolve the discrepancy.
E302	This resource is not available	The requested resource doesn't exist or isn't accessible.
E303	This feature is not available	The feature is not enabled for your account. Contact support.

Limit Errors

Code	Description	Resolution
E400	Brand is temporarily unavailable, please try again later	Rate limit exceeded. Wait and retry. Check your rate limit allocation.

---

HTTP Status Codes

Status	Meaning	Notes
200	Success	Check response body for order status (could still be FAILED)
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Invalid or expired token. Re-authenticate.
403	Forbidden	IP not whitelisted or access denied
404	Not Found	Resource doesn't exist
500	Server Error	Contact Hubble support with X-REQUEST-ID

Order Status vs HTTP Status

For order placement, HTTP 200 doesn't mean success. Always check the status field in the response body. An order can return HTTP 200 with status: "FAILED".

---

Error Handling Best Practices

1. Log Everything

Always log:

• X-REQUEST-ID
• Full error response
• Request payload (excluding sensitive data)
• Timestamp

// Example error logging
function logError(error, requestId, endpoint) {
  console.error({
    timestamp: new Date().toISOString(),
    requestId,
    endpoint,
    errorId: error.id,
    errorCode: error.code,
    message: error.message,
    debugMessage: error.debugMessage
  });
}

2. Handle Retries Properly

Error Type	Retry?	Notes
E100 (Brand disabled)	Yes	Wait 5-10 minutes
E200, E201 (Generation failed)	Yes	Wait 1-2 minutes, max 3 retries
E300 (Insufficient balance)	No	Top up wallet first
E150-E159 (Validation)	No	Fix request data first
E160 (Duplicate referenceId)	No	Generate new referenceId

3. User-Friendly Messages

Don't expose raw error messages to end users. Map error codes to friendly messages:

const userMessages = {
  'E100': 'This brand is temporarily unavailable. Please try again later.',
  'E102': 'This brand is currently not available.',
  'E150': 'The selected amount is not available for this brand.',
  'E200': 'Unable to generate your gift card. Please try again.',
  'E300': 'Service temporarily unavailable. Please contact support.',
};

4. Implement Circuit Breakers

For repeated failures on the same brand or endpoint, implement circuit breaker patterns to prevent cascading failures.

---

Troubleshooting with Support

When contacting Hubble support, provide:

1. X-REQUEST-ID — Critical for locating the request
2. Error code and message — The full error response
3. Timestamp — When the error occurred
4. Order ID or Reference ID — If applicable
5. Request payload — Excluding sensitive credentials

tip

The X-REQUEST-ID dramatically speeds up support resolution. Always generate, log, and retain it for every API call.