Errors

Every /api/v1 error has the same JSON shape: a stable code to branch on, a human message that may change, and sometimes details.

Error shape

HTTP

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "property_out_of_scope",
    "message": "Some Properties are outside the Connection Scope",
    "details": { "property_ids": ["PROPERTY_ID"] }
  }
}

Error codes

Status	code	Meaning
401	`unauthorized`	The access token is missing, unknown, expired or revoked, or was issued before the account connected the App again. Refresh it; if refreshing fails, ask the owner to connect again.
401	`connection_revoked`	The owner revoked the App Connection (or your App revoked its own refresh token). Stop calling for this account and drop its tokens.
402	`subscription_blocked`	The ZenHost subscription of the account is blocked (unpaid, cancelled…). The connection is kept: tell your customer, calls work again once the subscription is restored.
403	`forbidden_permission`	Your App was not granted the Permission this endpoint requires.
403	`app_suspended`	ZenHost suspended your App, or no longer allows it on this account. Stop calling and contact ZenHost.
404	`not_found`	The resource does not exist or is outside the Connection Scope (both look the same), or the path is not an endpoint of `/api/v1`.
405	`method_not_allowed`	The endpoint exists but not with this HTTP method; the `Allow` header lists the accepted ones.
409	`idempotency_key_in_use`	A request with this `Idempotency-Key` is still being processed. Retry in a few seconds to get its answer.
422	`property_out_of_scope`	A requested Property is outside the Connection Scope; `details.property_ids` lists them.
422	`validation_failed`	The query, headers or body are invalid; `details.issues` points at each problem (`path`, `message`, and `maximum` when a value or list is too big).
422	`idempotency_key_reused`	This `Idempotency-Key` was already used on this App Connection with a different body.
422	`channel_unavailable`	The chosen channel cannot reach the guest of this booking. On `platform`: the Sales Channel has no messaging for this booking, no conversation exists there yet, or the host must restore their connection to that Sales Channel. On `email`: the account has no sending address. Nothing was sent; try another channel.
422	`missing_guest_contact`	The guest of this booking has no email address (for `email`) or phone number (for `sms`). Nothing was sent.
422	`sms_billing_unavailable`	The ZenHost subscription of the account cannot be billed for SMS. Nothing was sent and nothing was billed; use another channel.
429	`rate_limited`	Too many calls on this App Connection. Wait for the number of seconds in `Retry-After`.
500	`internal_error`	ZenHost failed to answer. Retry later with a back-off.
502	`attachment_unavailable`	The Sales Channel could not hand over the attachment right now. Retry later with a back-off.
502	`delivery_failed`	The message could not be delivered. `details.delivery_outcome` is `not_sent` when it certainly did not leave (safe to send again) or `unknown` when its fate is not known (read the messages of the booking before sending again).