Common API errors & How to handle

1. As a general rule, you should never retry a request on a 4xx error before attempting to fix the issue first.

• The 4xx errors indicate a problem with the call, not the service.
• The most common one is 400 which typically means there is an invalid parameter like the reservation ID or property ID is missing.
• The common special case is 401 (Unauthorized) where you should try to get a new auth token: access_token to refresh the token and can try the call again with the new auth token.

2. HTTP response code: 401
   {
   "error": "server_error",
   "error_description": "The authorization code is invalid or has expired."
   }
   Explanation: Based on the API keys automatic delivery or OAuth 2.0. authentication, this 401 error means that the 'authorization_code' is invalid or has expired.
   The 'authorization_code' is valid for 10 minutes and can only be used once. If you get this error, the user would need to re-authorize (start your app connection process again).
3. HTTP response code: 401
   {
   "error": "access_denied",
   "message": "The resource owner or authorization server denied the request."
   }
   Explanation: An invalid API key or no API key were included in the request. A valid API key needs to be included.
4. HTTP response code: 200
   {
   "success": false,
   "message": "User who approved this connection is not active anymore"
   }
   Explanation: The user who initially authorized the integration has been deactivated. A current user in the property should reconnect your App to restore the integration.
5. HTTP response code: 200
   {
   "success": false,
   "message": "Your request could not be fully completed. The property(ies) you are accessing have an invalid status. See details: canceled: XXX"
   }
   Explanation: The property is no longer active in Cloudbeds.
6. HTTP response code: 200
   {
   "success": false,
   "message": "None of the included property id's match the access_token user's property id"
   }
   The API key does not have access to the requested property.
7. HTTP response code: 429

A 429 error means "too many requests right now, wait a moment", and it includes how long to wait in the response (Retry-After). The correct handling is to pause for that long and retry, and to space the retries out slightly so that several parallel jobs don't all come back at the exact same moment. This way the sync slows down gracefully when it hits a limit instead of the whole run failing.