Error Handling & HTTP Status Codes

HTTP · Status Codes · Error Handling

Error Handling

The API uses standard HTTP status codes and structured JSON error messages for consistent error handling.

HTTP Status Codes

Code	Status	Description
200	OK	Request successful (GET, POST, DELETE)
201	Created	New resource created (POST)
400	Bad Request	Invalid request body or missing parameters
401	Unauthorized	No token or invalid token
403	Forbidden	Token does not have the required scopes
404	Not Found	Resource not found
409	Conflict	Resource cannot be deleted (safety check)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The access token is invalid or expired"
  }
}

Starting with v2.119.0, when a request is rejected, the API also specifies the reason in the ` reason ` field and in the ` X-XoPort-Deny-Reason` header, for example, ` deny_token_required ` (401, request without a token) or ` deny_ip_not_listed ` (403, address not in ` XOPORT_REST_IP_LIST`).

Common Error Codes

Code	HTTP	Description
`INVALID_GRANT_TYPE`	400	grant_type must be "client_credentials"
`INVALID_CLIENT`	401	Invalid client ID or secret
`INVALID_TOKEN`	401	Token is invalid or expired
`MISSING_TOKEN`	401	No Authorization header
`IP_NOT_ALLOWED`	403	Request from an address not listed in `XOPORT_REST_IP_LIST` (since v2.119.0)
`INSUFFICIENT_SCOPE`	403	Token does not have the required scope
`NOT_FOUND`	404	Resource not found
`HAS_SUBCATEGORIES`	409	Category has subcategories
`HAS_PRODUCTS`	409	Category contains products
`HAS_ARTICLES`	409	News category contains articles
`HAS_ORDERS`	409	Customer has orders
`RATE_LIMIT_EXCEEDED`	429	Too many requests

Best Practice

Always check the " success" field in the response and implement retry logic for 429 and 5xx errors.