Errors tell you what failed and what to do next. Every error uses the same JSON shape.
{
"type": "https://supahost.io/docs/api-errors#invalid_date",
"title": "Invalid request",
"status": 400,
"code": "invalid_date",
"detail": "arrivalFrom must use the YYYY-MM-DD format.",
"requestId": "6a660c5f-3e6f-4926-a24a-6292dd54fdd3",
"retryable": "no",
"errors": [
{ "field": "arrivalFrom", "message": "arrivalFrom must use the YYYY-MM-DD format.", "code": "invalid_date" }
]
}A code keeps its meaning and its HTTP status. New codes can appear, so treat an unknown code by its status and retryable.
Every error has a retryable member with one of three values. Read it instead of guessing from the status, because one status, such as 409, can carry each of them.
no: the same request fails the same way. Change the request, or change the records it names, before you send it again.now: send the same request again. Nothing it wrote was saved.after: wait for the seconds in theRetry-Afterheader, then send the same request again. The header is present exactly whenretryableisafter.
Send writes with an Idempotency-Key and reuse it on every retry. Supahost then applies the write at most once and replays the first response.
invalid_api_key(HTTP 401, do not retry as is): Supahost did not accept the key. The key can be absent, invalid, expired, or revoked.insufficient_scope(HTTP 403, do not retry as is): The key lacks the scope that the endpoint needs. The detail names it.rate_limit_exceeded(HTTP 429, retry afterRetry-After): The key used its requests for the current window.Retry-Aftergives the seconds until the window resets.sandbox_read_only(HTTP 403, do not retry as is): A test key attempted a write. Use a live key to change records.closure_permission_required(HTTP 403, do not retry as is): The key creator lacks active workspace membership or the availability.manage permission. The dedicated scope alone is not enough.flow_permission_required(HTTP 403, do not retry as is): The key creator can no longer run automations, or the key no longer has the flows:write scope.
A validation error lists every invalid field it found in the errors array, so you can fix them all before you send the request again. Each item has a field, a message and a code. The first item is the one detail describes, and the top-level code is its code.
A field is a dot path. An array index is a plain number, and an array body starts with its collection name: days.3.rate in a calendar write, roomTypes.0.capacity in a rooms write, ratePlans.1.baseRate.currency in a rate plans write, and stay.arrivalDate in a reservation. body names the request body as a whole.
The list holds at most 100 items. When a request has more invalid fields, the error also has errorsTruncated: true. A write with an invalid field saves nothing.
invalid_request(HTTP 400, do not retry as is): The general validation failure: a field is missing, the wrong type, or outside its allowed values.invalid_reference(HTTP 400, do not retry as is): A field points at a record that does not exist or is not active, such as aratePlanIdthat no longer belongs to the pool.invalid_date_range(HTTP 400, do not retry as is): A date is not real,fromfalls afterto, or the range exceeds the maximum span for that endpoint.invalid_date(HTTP 400, do not retry as is): A date does not use theYYYY-MM-DDformat. The field is named.invalid_datetime(HTTP 400, do not retry as is): A timestamp does not use the ISO 8601 format with a time-zone offset. The field is named.invalid_limit(HTTP 400, do not retry as is):limitis not an integer or falls outside the allowed range.invalid_status(HTTP 400, do not retry as is): Astatusfilter is not one of the values that the endpoint accepts.invalid_cursor(HTTP 400, do not retry as is): Supahost rejected the cursor. It can be invalid or belong to different filters.invalid_idempotency_key(HTTP 400, do not retry as is): TheIdempotency-Keyheader is empty or longer than 200 characters.missing_idempotency_key(HTTP 400, do not retry as is): The endpoint requires anIdempotency-Keyheader, such as a flow event.invalid_status_transition(HTTP 400, do not retry as is): A record cannot move between those two statuses, such as reopening a task that is already finished.invalid_property_id,invalid_reservation_id,invalid_task_id,invalid_conversation_id,invalid_webhook_id,invalid_delivery_id,invalid_flow_id,invalid_rate_plan_id,invalid_pool_id,invalid_block_id, andinvalid_adjustment_id(HTTP 400, do not retry as is): A path or query ID is not a UUID.invalid_flow_request(HTTP 400, do not retry as is): A flow event body is missing, is not valid JSON, uses another content type, or does not match the flow event shape.payload_too_large(HTTP 413, do not retry as is): A flow event body exceeds 32 KB, 16 nesting levels, or 5000 JSON values.night_value_required(HTTP 400, do not retry as is): On a property whose calendar is supplied by a connected source, a calendar entry would leave a night without a value the channel needs to sell it, or in a state the channel cannot show: a night with units to sell (an open night whose sellable count, before reservations and blocks, is above 0) needs a rate on each rate plan an active listing sells or the calendar prices, and on at least one rate plan of its pool, unless that plan is stopped from selling there (stopSell: true); an entry that sends a rate or reopens a plan (stopSell: false) on a night without an available count needs that count; an entry may not reopen a rate plan night that has no rate without sending one; and a count on a pool whose room type has another active pool needs a count on that pool too. A close or a stop never needs a value. Eacherrorsitem names a missing field and the rate plan. Send the missing values in the same request.count_time_required(HTTP 400, do not retry as is): A calendar entry that sendsavailableUnitsorclosedmust sendrevisionAtas a date-time andobservedAtas a date-time ornull. The field is named.count_time_in_future(HTTP 400, do not retry as is): A calendar entry sends arevisionAtor anobservedAtmore than 2 minutes after Supahost’s own time for the request. The field is named.calendar_result_too_large(HTTP 400, do not retry as is): The calendar request exceeds the row limit. Narrow the range or passinventoryPoolId.closure_pool_unavailableandclosure_date_unavailable(HTTP 400, do not retry as is): The inventory pool or property is inactive, the pool is an owner entitlement pool, or the date is in the past.not_found(HTTP 404, do not retry as is): The record does not exist in the key workspace.
These name a condition of the records the request touches.
idempotency_key_reused(HTTP 409, do not retry as is, or retry afterRetry-After): TheIdempotency-Keywas already used with a different request (no: use a new key), or the first request with it is still in progress (after).sync_in_progress(HTTP 409, retry afterRetry-After): A channel sync for the property, rate plan, or room type is pending or being retried, or the property’s channel setup is still running.blockedBynames the record. Retry once the sync completes.sync_failed(HTTP 409, do not retry as is): A channel sync for the property, rate plan, or room type failed and Supahost will not retry it, or the property’s channel setup is not complete.blockedBynames the record and the reason. Retrying cannot succeed: stop, and ask a person in your workspace to resolve it in Supahost.reference_changed(HTTP 409, retry now): Another write moved a rate plan or room typereferencewhile the request ran. The whole request rolled back; send it again.reference_in_use(HTTP 409, do not retry as is): Thereferencealready belongs to another record of that kind: a rate plan or room type on the property, or a property or reservation in the workspace. A create whose reference belongs to a property or reservation with different details answers this too. The whole request rolls back.reference_inactive(HTTP 409, do not retry as is): An entry without anidnames thereferenceof an inactive rate plan or room type. Clear or change the reference on that record by itsidfirst, or use another one.calendar_feed_managed(HTTP 409, do not retry as is): Belongs to a retired setup, in which a connected feed updated the property’s calendar. No property returns it.calendar_move_pending(HTTP 409, do not retry as is): Belongs to a retired setup, in which a property’s move from a connected feed to the API was not final yet. No property returns it.calendar_writes_paused(HTTP 409, retry afterRetry-After): Supahost paused calendar writes to the property. A calendar write to the property is refused whole. A rate plan or room type entry is refused when it would create one, or change thecapacityormaxOccupancyof a room type. Reads, and other updates to existing rate plans and room types, still work. Send the request again later.protected_calendar_closure(HTTP 409, do not retry as is): The write would reopen protected inventory or remove a protected stop sell, arrival, or departure restriction. The whole request rolls back, also withskipLocked=true. A calendar write names the nights inprotectedNights. Remove those entries, or remove the protection in the calendar or with the calendar-protections:write scope first.calendar_night_locked(HTTP 409, do not retry as is): The request includes a night that is locked in the Supahost calendar.lockedNightslists them with the lock reason, and the whole request rolls back. Unlock the nights, or sendskipLocked=trueto write the others.date_block_started(HTTP 409, do not retry as is): The block has started, so its dates cannot change. The quantity and the reason of a started block can still change.closure_changed(HTTP 409, do not retry as is): The protection ID was already released. Read the current protection first; an old ID cannot release a replacement.conversation_closed(HTTP 400, do not retry as is): Replies cannot be added to the closed conversation.replies_not_supported(HTTP 400, do not retry as is): The connection for the conversation cannot send messages.member_inactive(HTTP 400, do not retry as is): The API key owner is no longer an active workspace member.insufficient_inventory(HTTP 400, do not retry as is): The stay does not fit the sellable inventory for every night.channel_rate_plan(HTTP 400, do not retry as is): A direct reservation cannot use an OTA rate plan.channel_managed(HTTP 400, do not retry as is): The reservation belongs to a connected channel and must be changed there.reservation_cancelled(HTTP 400, do not retry as is): A cancelled reservation cannot be changed.reservation_completed(HTTP 400, do not retry as is): A started or completed reservation cannot be changed.unit_assignedandmultiple_items(HTTP 400, do not retry as is): The reservation needs the Supahost dashboard for this change.flow_unavailable(HTTP 409, do not retry as is): The flow is paused, expired, or has a different published trigger or version.flow_webhook_key_changed(HTTP 409, do not retry as is): The event key does not match the published webhook trigger.flow_scope_mismatch(HTTP 409, do not retry as is): The context does not match the published property scope of the flow.flow_context_unavailable(HTTP 409, do not retry as is): The context record is not active or cannot start this flow.webhook_endpoint_disabled(HTTP 409, do not retry as is): The webhook endpoint is turned off, so Supahost cannot send a delivery to it again. Turn the endpoint on first.webhook_delivery_in_flight(HTTP 409, do not retry as is): A delivery of the same event is still pending or retrying. Send it again only after it is delivered or exhausted.flow_changed(HTTP 409, do not retry as is): The flow changed before the event could be recorded. Read the flow again before sending another event.price_adjustment_limit_reached(HTTP 409, do not retry as is): The workspace already has the most price adjustments it can hold (100). Nothing was written. Remove one withDELETE /price-adjustments/{adjustmentId}or change an existing one.precondition_failed(HTTP 412, do not retry as is): The record changed after the version named inIf-Match. Nothing was written. Read the record again, apply your change to the new version, and send the newETag.
A channel sync problem names the record that blocks the write in blockedBy, with its type, id, and reason. Read that record to see its sync state. sync_in_progress clears by itself. sync_failed does not: it has no Retry-After header, so stop retrying and ask a person in your workspace to resolve the sync in Supahost.
write_conflict(HTTP 409, retry afterRetry-After): The request collided with another change at the same moment, and Supahost rolled it back. Send the same request again.service_busy(HTTP 503, retry afterRetry-After): Supahost could not finish the request in time. Send the same request again; send writes with the sameIdempotency-Key.internal_error(HTTP 500, do not retry as is): Supahost could not complete the request. A write may or may not have been saved: read the record before you change it again, or repeat it only with the sameIdempotency-Key.
Send the requestId to support. Never send the API key.