# API Error Handling

Our API uses a consistent error-handling structure. When an error occurs, the response will:

Include the appropriate HTTP status code (e.g., 400, 404, 500)

Contain an optional error field with the following schema:


```json
{
    "error": {
        "code": "3002",                         //The error code,
        "message":"Request validation failed.", //The error message.,
        "details": "validation errors"         //The HTTP error details.
    }
}
```

# Error Codes

## Playout API Error Codes

- *1001* – **EPISODE_NOT_FOUND**: The requested episode does not exist.
- *1002* – **DESCRIPTIONS_NOT_AVAILABLE**: Descriptions and further details for the requested episode are currently unavailable.
- *1003* – **EPISODE_NOT_AVAILABLE**: The episode exists but cannot be accessed at this time.
- *1004* – **AFFILIATE_NOT_AVAILABLE**: The affiliate information could not be retrieved.
- *1005* – **MERCHANTS_NOT_AVAILABLE**: The merchant list for the episode is unavailable.
- *1006* – **MERCHANT_NOT_FOUND**: The specified merchant does not exist.
- *1007* – **TIMELINE_NOT_AVAILABLE**: No timeline data is available for the episode.
- *1008* – **SCENE_NOT_FOUND**: The requested scene could not be found in the episode.
- *1009* – **DATA_NOT_FOUND**: The expected data could not be located.
- *1010* – **TRACKING_NOT_VALID**: No tracking session found or session data is invalid.
- *1011* – **CONTENT_NOT_FOUND**: The requested content could not be located.
- *1012* – **FORMAT_NOT_FOUND**: The requested format or series could not be found.
- *1013* – **INVALID_FILTER**: The provided filter parameters are invalid or malformed.
- *1014* – **PAGINATION_ERROR**: Error occurred during pagination processing.


## Basket API Error Codes

- *2001* – **PAYMENT_PROVIDER_NOT_SUPPORTED**: The provided payment method is not supported.
- *2002* – **AUTHORIZATION_HEADER_INVALID**: The authorization header is missing or malformed.
- *2003* – **AFFILIATE_NOT_EXISTS**: The affiliate identifier does not match any known affiliate.
- *2004* – **MISSING_AFFILIATE**: The request is missing required affiliate context.
- *2005* – **BASKET_NOT_FOUND**: The specified basket could not be found.
- *2006* – **PRODUCT_NOT_IN_BASKET**: The product is not currently in the basket.
- *2008* – **CHECKOUT_SESSION_EXPIRED**: The checkout session has expired and is no longer valid.
- *2012* – **PAYMENT_FAILED**: The payment process failed or was declined.
- *2013* – **INSUFFICIENT_STOCK**: Not enough stock available for the requested quantity.
- *2014* – **BASKET_LIMIT_EXCEEDED**: The maximum basket size has been exceeded.
- *2015* – **INVALID_PRODUCT_COUNT**: The product count specified is invalid.
- *2016* – **TRANSFER_TOKEN_EXPIRED**: The basket transfer token has expired.
- *2017* – **TRANSFER_TOKEN_INVALID**: The basket transfer token is invalid or malformed.
- *2018* – **CHECKOUT_ALREADY_ACTIVE**: A checkout session is already active for this basket.
- *2019* – **INVALID_CURRENCY**: The specified currency is not supported.
- *2020* – **SHIPPING_CALCULATION_ERROR**: Error occurred while calculating shipping costs.
- *2021* – **TAX_CALCULATION_ERROR**: Error occurred while calculating tax amounts.
- *2022* – **DISCOUNT_NOT_APPLICABLE**: The discount code is not applicable to current items.
- *2023* – **USER_AUTHENTICATION_REQUIRED**: User authentication is required for this operation.
- *2024* – **COMFORT_FUNCTION_UNAVAILABLE**: Comfort functions are not available for this user type.
- *2025* – **BASKET_TRANSFER_FAILED**: Failed to transfer the basket to the target system.


## Generic API Error Codes

- *3000* – **UNKNOWN_ERROR**: An unknown error occurred.
- *3001* – **INTERNAL_SERVER_ERROR**: An unexpected error occurred on the server.
- *3002* – **REQUEST_VALIDATION_ERROR**: The request did not pass input validation rules.
- *3003* – **DATABASE_ERROR**: A database operation failed.
- *3004* – **EXTERNAL_SERVICE_ERROR**: An external service is unavailable or returned an error.
- *3005* – **RATE_LIMIT_EXCEEDED**: The request rate limit has been exceeded.
- *3006* – **CONFIGURATION_ERROR**: A configuration error was detected.
- *3007* – **CACHE_ERROR**: An error occurred while accessing cached data.


## Product API Error codes

- *4001* – **NOT_A_MANAGED_SHOP**: The shop is not managed by the marketplace.
- *4002* – **SHOP_CONFIGURATION_INVALID**: The shop configuration is invalid or incomplete.


## System Error Codes

- *5001* – **SERVICE_UNAVAILABLE**: The service is temporarily unavailable.
- *5002* – **MAINTENANCE_MODE**: The system is currently in maintenance mode.
- *5003* – **VERSION_NOT_SUPPORTED**: The requested API version is not supported.
- *5004* – **DEPRECATED_ENDPOINT**: The requested endpoint has been deprecated.