Error Codes

Comprehensive list of HTTP status codes and error responses you may encounter when using the CASY API.

HTTP Code	Error Code	Description	Possible Causes & Solutions
200	`OK`	Request successful	No action required. Response will include requested data.
400	`invalid_parameter`	Invalid query parameter or request format	• Check parameter names and values • Ensure dates are in YYYY-MM-DD format • Verify numeric values are correct type • Confirm all required parameters are provided
401	`missing_token`	Authentication header is missing	• Include Authorization header in request • Format: `Authorization: Bearer your-token-here` • Ensure header name is correct (case-sensitive)
401	`invalid_token`	Token format is invalid or malformed	• Check token has no extra spaces or characters • Verify token hasn't been truncated • Ensure you're using the raw token value • Request a new token from support@casy.ch if corrupted
401	`invalid_token_or_not_found`	Token is invalid or was not found in database	• Verify token is correct and hasn't expired • Check token exists in the system • Request a new token if it was revoked • Contact support@casy.ch for token issues
403	`forbidden`	Token lacks permission for resource or hotel	• Verify you have access to this specific hotel/CASY ID • Check error message for allowed hotels • Request additional hotel permissions from support • Use /introspect endpoint to see your permissions
403	`forbidden_action`	Token doesn't have required action/permission	• Use /introspect to see your available actions • Request specific permissions (e.g., reservations:read) • Contact support@casy.ch to update token permissions • Different actions are needed for different endpoints
404	`not_found`	Resource was not found	• Verify the resource ID is correct • Check URL path is valid • Ensure the resource hasn't been deleted • Use list endpoints to verify resource exists
404	`unknown_hotel`	Specified hotel/CASY ID doesn't exist	• Verify CASY ID is correct and numeric • Use /hotels endpoint to list available hotels • Check with your account manager if CASY ID changed • Ensure you have access to this specific hotel
429	`rate_limited`	Rate limit exceeded for your token	• Wait before making additional requests • Response includes `window_seconds` and `limit` • Implement exponential backoff in client code • Request higher rate limit if needed (support@casy.ch)
500	`internal_error`	Internal server error	• Retry the request after a short delay • Check API status page for incidents • Contact support@casy.ch with request details • Include request ID if available
502	`central_db_unavailable`	Central database connection failure	• The API servers cannot reach the central database • Retry after a few seconds • Check status page for maintenance windows • Contact support@casy.ch if problem persists
502	`tenant_db_unavailable`	Tenant database connection failure or data discrepancy	• The tenant-specific database is unreachable • May indicate data consistency issues • Retry the request • Contact support@casy.ch if persists

Error Response Format

All error responses follow this standard format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "detail": "Additional context if available"
}

Common Troubleshooting

Got 401? Check your token is included and hasn't expired
Got 403? Use /introspect to see what you can access
Got 404? Verify the CASY ID and resource ID exist
Got 429? Implement request throttling and retry logic
Got 502? These are temporary - implement exponential backoff

Need Help?

If you encounter persistent errors not listed here:

Email: support@casy.ch
Include the request ID (if available) and full error response
Check recent changelog for API changes that might affect your integration