Error Handling

All error responses follow a consistent structure:

{
  "errorModel": {
    "errorCode": "ERROR_CODE",
    "message": "Human-readable description",
    "descriptors": ["additional", "context"]
  }
}

Error Codes

Error Code	HTTP Status	Description
HYBRID_REVO_TOKEN_CONFIGURATION_ALREADY_EXISTS	400	A configuration already exists for this organization. Only one is allowed.
HYBRID_REVO_TOKEN_CONFIGURATION_NOT_ENABLED	400	The configuration exists but is currently disabled.
HYBRID_REVO_TOKEN_TRANSACTION_NOT_FOUND	404	No transaction found for the given code.
HYBRID_REVO_TOKEN_PRODUCT_NOT_IN_CURRENT_VERSION	400	One or more product IDs are not part of the current configuration version.
HYBRID_REVO_TOKEN_TRANSACTION_NOT_ENOUGH_ACTIVE_ITEMS	400	The requested return quantity exceeds available active items for that category.
DEVICE_CANNOT_ACCESS_HYBRID_REVO_TOKEN_TRANSACTION	403	The device is not authorized to access this transaction (different location).
HYBRID_REVO_TOKEN_EXTERNAL_PRODUCT_NOT_FOUND	404	The product ID does not exist in the system.
HYBRID_REVO_TOKEN_TRANSACTION_EMPTY_ITEMS	400	The transaction request contains no items.
HYBRID_REVO_TOKEN_PRODUCT_NOT_IN_DEVICE_PLACE	403	The product is not available at the device's assigned location.
DUPLICATE_CATEGORY_ID_IN_HYBRID_REVO_TOKEN_TRANSACTION	400	The same category ID appears more than once in the validate request.

Recommended Handling

Configuration Errors

If you receive HYBRID_REVO_TOKEN_CONFIGURATION_NOT_ENABLED, your POS should skip Hybrid Revo Token issuance and process the order normally without container deposits.

Transaction Errors

For HYBRID_REVO_TOKEN_TRANSACTION_NOT_FOUND, prompt the operator to verify the transaction code was entered correctly.

For HYBRID_REVO_TOKEN_TRANSACTION_NOT_ENOUGH_ACTIVE_ITEMS, refresh the transaction preview to show the current state -- items may have expired since the last preview.

Access Errors

DEVICE_CANNOT_ACCESS_HYBRID_REVO_TOKEN_TRANSACTION and HYBRID_REVO_TOKEN_PRODUCT_NOT_IN_DEVICE_PLACE indicate a location mismatch. The guest may need to return containers at a device belonging to the correct location.