Wallet Services Error Codes
Wallet Services error HTTP status codes and messages
General / Common Errors
These errors apply across all Wallet Services endpoints.
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| header.requestId.missing | 400 Bad Request | The requestId header is missing. Provide a valid Unique Request identifier and resend the request. |
| header.merchantId.missing | 400 Bad Request | The merchantId header is missing. Provide a Blackhawk issued unique identifier for the merchant who is making the call. |
| header.millisecondsToWait.invalid | 400 Bad Request | The millisecondsToWait header value is invalid. Accepted range is 0–30000. |
| request.walletId.missing | 400 Bad Request | The walletId field is missing from the request. |
| request.walletId.invalid | 400 Bad Request | The walletId path parameter is not a valid UUID format. Provide a correctly formatted Unique identifier for the wallet. |
| request.walletId.invalidLength | 400 Bad Request | The walletId value exceeds the maximum allowed length. |
| request.payLoad.invalid | 400 Bad Request | The request body is malformed or cannot be parsed. Ensure the body is valid JSON. |
| request.url.path.invalid | 400 Bad Request | The URL path parameter is invalid. |
| request.duplicate.url.mismatch | 409 Conflict | A request with the same requestId was already received at a different endpoint. Use a new requestId for a different endpoint. |
Create Wallet
Endpoint: POST /api/v2/wallet
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| request.userId.missing | 400 Bad Request | The userId field is present but empty. Provide a valid non-empty UUID. |
| request.userId.invalid | 400 Bad Request | The userId is not a valid UUID format. Provide a correctly formatted UUID. |
| request.partnerRefUserId.missing | 400 Bad Request | The partnerRefUserId field is present but empty. Provide a valid non-empty value. |
| request.partnerRefUserId.invalid | 400 Bad Request | The partnerRefUserId contains invalid characters. Provide an alphanumeric value without special characters. |
| request.description.invalidLength | 400 Bad Request | The description field exceeds the maximum allowed length of 128 characters. |
| request.description.invalid | 400 Bad Request | The description field contains invalid or unsupported characters. |
| request.walletIdentifier.missing | 400 Bad Request | No wallet identifier was provided. Supply either a userId or partnerRefUserId. |
| request.walletIdentifiers.both.present | 400 Bad Request | Both userId and partnerRefUserId were provided. Only one wallet identifier is allowed per request. |
| request.riskAttributes.invalid | 400 Bad Request | The riskAttributes field must be a JSON object. Strings and arrays are not accepted. |
| request.partnerConsumerId.invalidLength | 400 Bad Request | The partnerConsumerId field exceeds the maximum allowed length. |
| createWallet.failed.userId.notFound | 404 Not Found | The userId provided could not be found in the BHN system. Provide a valid registered user ID. |
| createWallet.failed.serviceUnavailable | 503 Service Unavailable | A downstream service (e.g., Person Service) is temporarily unavailable. This is a retryable error. |
Add Balance
Endpoint: POST /api/v2/wallet/{walletId}/add
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| request.item.missing | 400 Bad Request | The item object is missing from the request body. |
| request.item.type.missing | 400 Bad Request | The item.type field is missing. |
| request.item.type.invalid | 400 Bad Request | The item.type value is not recognized. |
| request.item.itemType.missing | 400 Bad Request | The item.itemType field is missing. Provide a valid item type (e.g., STORE_VALUE_ACCOUNT, CLOSED_LOOP_PREPAID). |
| request.item.itemType.invalid | 400 Bad Request | The item.itemType value is not recognized. Accepted values are STORE_VALUE_ACCOUNT and CLOSED_LOOP_PREPAID. |
| request.item.upc.missing | 400 Bad Request | The item.upc field is required for STORE_VALUE_ACCOUNT items. |
| request.item.upc.invalid | 400 Bad Request | The item.upc value is invalid. Provide valid identifier for the store value product. |
| request.item.amount.missing | 400 Bad Request | The item.amount field is required for STORE_VALUE_ACCOUNT items. |
| request.item.amount.invalid | 400 Bad Request | The item.amount value is invalid. Provide valid amount to be loaded to the wallet account. |
| request.item.cardNumber.missing | 400 Bad Request | The item.isBhnVerified field is required for CLOSED_LOOP_PREPAID / OPEN_LOOP_PREPAID items. |
| request.item.cardNumber.invalid | 400 Bad Request | The item.cardNumber value is invalid. Provide a closed Loop Gift Card number (16-20 digits). |
| request.item.pin.missing | 400 Bad Request | The item.pin is required for CLOSED_LOOP_PREPAID items. |
| request.item.pin.invalid | 400 Bad Request | The item.pin value is invalid. Provide a Personal Identification Number associated with the Closed Loop card (4 to 10 digits). |
| request.item.productLineId.missing | 400 Bad Request | The item.productLineId is required for CLOSED_LOOP_PREPAID items. |
| request.item.productLineId.invalid | 400 Bad Request | The item.productLineId value is invalid. Provide a Unique Product Line ID issued by BHN for the closed loop gift card program. |
| request.item.expiryMonth.missing | 400 Bad Request | The item.expiryMonth value is missing. |
| request.item.expiryMonth.invalid | 400 Bad Request | The item.expiryMonth value is invalid. Provide Expiration month of the Open Loop Gift Card in MM format. |
| request.item.expiryYear.missing | 400 Bad Request | The item.expiryYear value is missing. |
| request.item.expiryYear.invalid | 400 Bad Request | The item.expiryMonth value is invalid. Provide Expiration year of the Open Loop Gift Card in YYYY format |
| request.item.description.invalidLength | 400 Bad Request | The item.description field exceeds the maximum allowed length. |
| request.securityCode.missing | 400 Bad Request | The itemId field is missing from the request. |
| request.securityCode.invalid | 400 Bad Request | The itemId value contains invalid or unsupported characters. |
| request.item.loyaltyId.missing | 400 Bad Request | loyaltyId is missing. Provide Unique loyalty account or card identifier issued by the loyalty program provider. |
| request.item.provider.missing | 400 Bad Request | provider is missing. Provide name of the loyalty program provider. |
Redeem / Spend Balance
Endpoint: POST /api/v2/wallet/{walletId}/redeem
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| request.totalAmount.value.missing | 400 Bad Request | The totalAmount.value field is missing from the request. |
| request.totalAmount.value.invalid | 400 Bad Request | The totalAmount.value is invalid (e.g., negative or zero). |
| request.totalAmount.currencyCode.missing | 400 Bad Request | The totalAmount.currencyCode field is missing from the request. |
| request.totalAmount.currencyCode.invalid | 400 Bad Request | The totalAmount.currencyCode value is invalid. Provide a valid ISO 4217 currency code (e.g., USD). |
| request.items.itemId.missing | 400 Bad Request | The itemId is missing from one or more entries in the items array. |
| request.items.itemId.invalid | 400 Bad Request | One or more itemId values are not valid. Provide Unique identifier of the wallet item from which to redeem |
| request.items.amount.value.missing | 400 Bad Request | The items.amount.value field is missing from the request. |
| request.items.amount.value.invalid | 400 Bad Request | The items.amount.value field is invalid. Provide valid amount. |
| request.items.amount.currencyCode.missing | 400 Bad Request | The items.amount.currencyCode field is missing. |
| request.items.amount.currencyCode.invalid | 400 Bad Request | The items.amount.currencyCode field is invalid. Provide Currency code in ISO 4217 format. |
| redeem.failed.internalError | 500 Internal Server Error | An internal error occurred during the redemption process. This is a retryable error. |
| redeem.items.failedToGetBalances | 500 Internal Server Error | An internal error occurred during the redemption process. This is a retryable error. |
Get Balances
Endpoint: GET /api/v2/wallet/{walletId}/balanceSummary
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| getSummary.failed.walletId.notFound | 404 Not Found | The specified wallet ID was not found. |
| getSummary.failed.serviceUnavailable | 503 Service Unavailable | The Balance Summary service is temporarily unavailable. This is a retryable error. |
Get Wallet Activity
Endpoint: GET /api/v2/wallet/{walletId}/activity
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| getWalletActivity.failed.wallet.notFound | 404 Not Found | The specified wallet could not be found. |
| getWalletActivity.failed.serviceUnavailable | 503 Service Unavailable | The Wallet Activity service is temporarily unavailable. This is a retryable error. |
Get Wallet Items
Endpoint: GET /api/v2/wallet/{walletId}/item/lookup
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| getDetails.failed.walletId.notFound | 404 Not Found | The specified wallet could not be found. |
| getItem.failed.serviceUnavailable | 503 Service Unavailable | The Get Items service is temporarily unavailable. This is a retryable error. |
Get Wallet Item Activity
Endpoint: GET /api/v2/wallet/{walletId}/item/activity
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| getWalletTransaction.failed.wallet.notFound | 404 Not Found | The specified wallet could not be found. |
| getWalletTransaction.failed.serviceUnavailable | 503 Service Unavailable | The Wallet Item Activity service is temporarily unavailable. This is a retryable error. |
Remove Items
Endpoint: POST /api/v2/wallet/{walletId}/items/remove
Note: A successful HTTP 200 response may still contain per-item failures. Always check the status field for each item in the response body.
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| request.items.itemId.missing | 400 Bad Request | The items.itemId field is missing from the request. Provide Wallet item identifier in the BHN system. |
| removeItem.failed.item.notFound | 200 (item-level) | The specified item could not be found in the wallet. Returned as a per-item failure inside the response body. |
| removeItem.failed.item.hasBalance | 200 (item-level) | The item cannot be removed because it still has a remaining balance. Drain the balance before removing. |
| removeItem.failed.serviceUnavailable | 503 Service Unavailable | The Remove Item service (BAG) is temporarily unavailable. This is a retryable error. |
Delete Wallet
Endpoint: POST /api/v2/wallet/{walletId}/delete
| Error Codes | HTTP Response Code | Error Description |
|---|---|---|
| wallet.notFound via BAG | 404 Not Found | The specified wallet could not be found. |
| deleteWallet.failed.wallet.notEmpty | 409 Conflict | The wallet cannot be deleted because it still contains items. Remove all items before deleting the wallet. |
| deleteWallet.failed.serviceUnavailable | 503 Service Unavailable | The Delete Wallet service (BAG) is temporarily unavailable. This is a retryable error. |
Updated about 1 month ago
Did this page help you?