Errors

The API uses conventional HTTP status codes and a single, predictable error shape. Any non-2xx response has a JSON body with an error object.

The error envelope

{
  "error": {
    "code": "validation_error",
    "message": "check_out must be after check_in.",
    "details": {
      "field": "check_out"
    },
    "request_id": "req_8Kd2p1"
  }
}

Field	Description
code	Stable, machine-readable string. Branch on this, not on message.
message	Human-readable explanation. May change; do not parse it.
details	Optional object with field-level or context-specific information.
request_id	Identifier for this request. Include it in support tickets.

Request IDs

Every response, success or failure, includes an X-Request-Id header. On errors the same value appears in error.request_id. Log it on your side so any request can be traced end to end.

X-Request-Id: req_8Kd2p1

Error codes

HTTP	code	Meaning
401	unauthorized	Missing, malformed, or invalid API key.
403	forbidden_scope	The key is valid but not scoped for this endpoint or action.
404	not_found	The resource does not exist, or is not visible to this key's mode.
422	validation_error	The request body or parameters failed validation. See details.
429	rate_limited	Per-key rate limit exceeded. Back off and retry.
409	idempotency_conflict	The Idempotency-Key was reused with a different request body.
409	reservation_conflict	The requested rooms or dates are no longer available.
409	availability_closed	Availability is closed for the requested room type and dates.
409	conflict	The write would break a one-per-resource rule, such as setting a second default room type on a property.
409	vendor_not_accepting_orders	The business is online but cannot take orders or bookings until its card is on file with Coastly.
402	gateway_not_connected	A payment gateway is required for this action but is not connected.
500	internal_error	Something went wrong on our side. Safe to retry idempotent calls.

Handling errors

• Switch on code. It is the stable contract; message and details are for humans and logs.
• Retry 429 and 5xx with exponential backoff. For 429, respect the Retry-After header when present. See rate limits.
• Do not retry 4xx other than 429 without changing the request; they indicate a client-side problem.
• 409 conflicts are actionable: idempotency_conflict means you reused a key with a changed body; reservation_conflict and availability_closed mean inventory moved, so refresh availability and try different rooms or dates; conflict on a room type means the property already has a default room, so unset it first (PATCH it with is_default: false) and retry.
• Always capture request_id so support can locate the exact request.