Errors
Status codes, error bodies, and how to act on them.
Use the HTTP status for control flow. Messages vary by PMS, so keep the whole response body in your logs for debugging, but don't parse it to make decisions.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | Validation failed, or the request conflicts with current availability or state. | Fix the request, or show the guest other options. Don't retry unchanged. |
401 | The API key is missing or invalid. | Check the x-calry-api-key header. |
403 | The key is valid but can't use this endpoint. | Ask OnSeason to check your key's access. |
404 | The listing, unit, or reservation doesn't exist or isn't available to your key. | Refresh your catalogue, or check the ID. |
422 | On a reservation: the PMS accepted the booking but OnSeason couldn't finish recording it. | Don't book again. Contact support with the reference in the message. |
500 | OnSeason or the PMS couldn't complete the request. | Retry reads with backoff. For reservations and cancellations, follow Handle timeouts and retries. |
Validation errors
Validation errors return 400 and list the fields that failed:
{
"message": "Validation Failed",
"details": [
{
"property": "listingID",
"messages": ["listingID must be a UUID"]
}
],
"timestamp": "2026-07-15T10:00:00.000Z",
"path": "/api/v1/quote"
}Authentication errors
{
"timestamp": "2026-07-15T10:00:00.000Z",
"path": "/api/v1/search",
"message": "Authentication failed",
"details": []
}