Errors
Every error this API returns. Branch on code, never on message —
codes are part of the contract, messages are written for people and may be reworded.
The failure shape
{
"success": false,
"code": "UNIT_INACTIVE",
"message": "units.0 refers to a unit that is no longer sellable.",
"errors": {
"units.0": {
"inventory_id": 31,
"is_active": false
}
}
}
errors is present only when there is structured detail to give. Its shape depends
on the code and is documented per code below.
All codes
| Status | Code | Meaning |
|---|---|---|
| 422 | VALIDATION_FAILED |
The request body failed validation. errors is Laravel's field bag: an object keyed by field path, each holding an array of messages. |
| 422 | IDEMPOTENCY_KEY_REQUIRED |
A create — POST /bookings, POST /properties or POST /properties/bulk — was sent without a usable Idempotency-Key header. |
| 422 | IDEMPOTENCY_KEY_REUSED |
The key has already been used, with a different request body. Doorloom fingerprints the body (SHA-256 over key-sorted JSON), so key order does not matter but any value change does. Keys are shared across every create endpoint, so a booking key resent on a property create is a reuse too. |
| 409 | IN_PROGRESS |
Two of your requests overlapped and this one lost. Either the same Idempotency-Key is still being processed, or another request is creating the same external id or changing the same property. |
| 422 | PROPERTY_NOT_MAPPED |
The property reference is missing, unknown, or outside your integration's coverage. Coverage is what you created through POST /properties plus what Doorloom staff mapped, and only ever includes properties the brand owner owns outright, never cohosted ones. |
| 422 | PROPERTY_ARCHIVED |
The property exists and is covered, but the host has archived it. Archived properties are off-market: they cannot take bookings, and they cannot be edited through the API. |
| 409 | PROPERTY_EXTERNAL_ID_EXISTS |
The external_id you sent is already mapped to a property of your integration. On a create, that property was not created; on an update, the mapping was not changed. errors.doorloom_id tells you which property holds the id, so you can store the mapping or pick a different id. |
| 422 | UNIT_NOT_MAPPED |
A booking's units[] line, or the unit of an availability write, names a unit alias Doorloom does not know, or one that belongs to a different property. |
| 422 | UNIT_INACTIVE |
The unit is mapped but no longer sellable — deactivated or deleted by the host. |
| 409 | UNAVAILABLE |
There is no free unit for the whole stay, or a unit you pinned is taken. Nothing was written. Doorloom never silently swaps a pinned unit for another. |
| 409 | BOOKING_CANCELLED |
A cancelled booking is terminal. It cannot be modified or un-cancelled. |
| 412 | REVISION_MISMATCH |
You sent If-Match and the booking has changed since you read it. The revision increments on every change, including host-side edits made in the Doorloom app. |
| 429 | SYNC_TOO_SOON |
A full re-sync was requested too recently. One is allowed every 24 hours. |
| 429 | RATE_LIMITED |
You exceeded one of the rate limits. The standard Retry-After and X-RateLimit-* headers are set on the response. The second message is the calendar-write limit: 10 calls per property per hour on each of PUT availability, rates and restrictions. |
| 404 | NOT_FOUND |
No such booking or property for this integration. Another integration's booking or property is not found rather than forbidden, so ids cannot be probed across partners. On a property write, a property whose coverage staff have removed is also not found. |
| 401 | UNAUTHENTICATED |
No API key, or a key that is not valid. Rotating your API key invalidates the previous one immediately. |
| 403 | NOT_INTEGRATION_TOKEN |
The bearer token is valid but is not an integration API key — it belongs to another Doorloom token surface. Integration keys are the only credential this API accepts. |
| 403 | INTEGRATION_DISABLED |
Doorloom staff disabled this integration. No events are recorded and no API call succeeds. This is distinct from paused: a paused integration keeps full API access and only stops receiving webhooks. |
Retrying safely
| Field | Type | Description |
|---|---|---|
429
|
retry | Back off for Retry-After (or errors.retry_after) seconds, then retry the same request. |
409 IN_PROGRESS
|
retry | A race with your own earlier request. Retry in a few seconds: with the same key when the message says the key is still being processed, with a new key when it says the external id is being created. See the note below. |
5xx
|
retry | Retry with backoff. On a create, reuse the same Idempotency-Key so a request that actually succeeded is not duplicated. |
4xx (everything else)
|
do not retry | The request is wrong, or the world is. Fix it or surface it. Retrying unchanged produces the same answer. |
A refused create replays, it does not re-race
409 or 422 from
POST /bookings,
POST /properties or
POST /properties/bulk is
stored against your idempotency key once the request has started work. Retrying with the same key
returns the same refusal rather than attempting the write again. To genuinely retry after fixing
the problem, use a new key.
That includes one kind of
409 IN_PROGRESS: the one whose message says a booking or a
property with this external id is being created. Two of your requests for the same
external id overlapped, and this one lost. It is stored, so the same key keeps answering
409. Retry with a new key: the external id guard then hands you the booking that won
(200 with duplicate: true) or, for a property,
409 PROPERTY_EXTERNAL_ID_EXISTS naming it.
Four refusals happen before any work starts and are not stored, so the same key can be sent again: a body that fails validation,
IDEMPOTENCY_KEY_REQUIRED,
IDEMPOTENCY_KEY_REUSED, and the IN_PROGRESS whose message says the key
itself is still being processed.Reference
VALIDATION_FAILED
422
The request body failed validation. errors is Laravel's field bag: an object keyed by field path, each holding an array of messages.
What to do: Read errors; each key is the dotted path of the offending field.
Messages:
Validation failedThe same unit is referenced by more than one line.Unknown type '{type}'.
errors
| Field | Type | Description |
|---|---|---|
{field path}
|
array of strings, e.g. guest.mobile, units.0.adults, properties.3.address.city on a bulk call |
|
units
|
["duplicate unit"] when two booking lines name the same unit |
|
units.{i}.external_id
|
on a property write: the alias is already mapped to another unit of your integration, or is duplicated in the request | |
units.{i}.inventory_id
|
on a property update: the unit does not belong to the property | |
units.{i}.name
|
on a property update: a unit addressed by an unknown alias needs a name to be created |
|
units.{i}.is_active
|
on a property update: the default unit cannot be deactivated, or the listing's inventory limit is reached | |
units.{i}
|
on a property update: the entry names neither inventory_id nor external_id |
|
updates.{i}.from
|
on a calendar write: the date is in the past, or the range overlaps an earlier one in the same request | |
updates.{i}.to
|
on a calendar write: beyond the 730-day horizon, or the request spans more than 92 days | |
updates.{i}.units_cap
|
on an availability write: above the property's unit count, or sent together with unit |
|
updates.{i}.unit
|
on a calendar write: the unit reference is empty, or a unit was sent to rates or restrictions, which are per property | |
updates.{i}
|
on a calendar write: the range carries none of the endpoint's fields |
IDEMPOTENCY_KEY_REQUIRED
422
A create — POST /bookings, POST /properties or POST /properties/bulk — was sent without a usable Idempotency-Key header.
What to do: Send Idempotency-Key: <8–128 characters>. A UUID per create attempt is ideal.
Messages:
Send an Idempotency-Key header (8–128 characters) with every booking create.Send an Idempotency-Key header (8–128 characters) with every property create.Send an Idempotency-Key header (8–128 characters) with every bulk property create.
IDEMPOTENCY_KEY_REUSED
422 The key has already been used, with a different request body. Doorloom fingerprints the body (SHA-256 over key-sorted JSON), so key order does not matter but any value change does. Keys are shared across every create endpoint, so a booking key resent on a property create is a reuse too.
What to do: Use a new key for a new create. Reuse a key only to retry the identical request.
Message: This Idempotency-Key was already used with a different request body.
IN_PROGRESS
409
Two of your requests overlapped and this one lost. Either the same Idempotency-Key is still being processed, or another request is creating the same external id or changing the same property.
What to do: Retry in a few seconds. When the message says the key is still being processed, retry with the same key; a claim left in progress for 60 seconds is taken over automatically. When it says the external id is being created, the refusal is stored against your key, so retry with a new key: you get the booking that won (200, duplicate: true) or PROPERTY_EXTERNAL_ID_EXISTS naming the property. When it says the property is being modified, repeat the update or the calendar write.
Messages:
A request with this Idempotency-Key is still being processed. Retry shortly.A booking with this external id is being created. Retry shortly.A property with this external_id is being created. Retry shortly.This property is being modified by another request. Retry shortly.
PROPERTY_NOT_MAPPED
422
The property reference is missing, unknown, or outside your integration's coverage. Coverage is what you created through POST /properties plus what Doorloom staff mapped, and only ever includes properties the brand owner owns outright, never cohosted ones.
What to do: Call GET /properties for the authoritative list of what you cover.
Messages:
Provide property.doorloom_id or property.external_id.This property is not covered by your integration.This property no longer exists.The booking no longer references a property.One or more property_ids are not covered by your integration.
errors
| Field | Type | Description |
|---|---|---|
property
|
the reference you sent, echoed back | |
property_ids
|
array of the uncovered ids, on POST /sync |
PROPERTY_ARCHIVED
422 The property exists and is covered, but the host has archived it. Archived properties are off-market: they cannot take bookings, and they cannot be edited through the API.
What to do: Stop selling it. A property.changed event with status: "archived" announces this. Unarchiving happens in the Doorloom app.
Messages:
This property is archived and cannot be booked.{property name} is archived and cannot be booked.This property is archived and cannot be modified through the API.
errors
| Field | Type | Description |
|---|---|---|
property
|
{"doorloom_id": 902} (on a booking, with the first message only) |
PROPERTY_EXTERNAL_ID_EXISTS
409
The external_id you sent is already mapped to a property of your integration. On a create, that property was not created; on an update, the mapping was not changed. errors.doorloom_id tells you which property holds the id, so you can store the mapping or pick a different id.
What to do: If it is the same listing, store errors.doorloom_id and move on (or PUT /properties/{id} to change it). If it is a different listing, send a different external_id. A retry with the same Idempotency-Key replays this refusal; use a new key once the body is corrected.
Message: A property with this external_id already exists for your integration.
errors
| Field | Type | Description |
|---|---|---|
external_id
|
the id you sent, echoed back | |
doorloom_id
|
integer — the property that already carries it |
UNIT_NOT_MAPPED
422
A booking's units[] line, or the unit of an availability write, names a unit alias Doorloom does not know, or one that belongs to a different property.
What to do: Aliases are the ones you set on POST /properties / PUT /properties/{id} or that Doorloom staff mapped, published on inventory.changed and GET /properties. Re-read them, or omit the unit reference to let Doorloom allocate any free unit.
Messages:
units.{i}.external_unit_id is not mapped for this property.units.{i} does not belong to this property.updates.{i}.unit.external_unit_id is not mapped for this property.updates.{i}.unit does not belong to this property.
errors
| Field | Type | Description |
|---|---|---|
units.{i}
|
the offending line, echoed back | |
updates.{i}.unit
|
on an availability write: the offending unit reference, echoed back |
UNIT_INACTIVE
422 The unit is mapped but no longer sellable — deactivated or deleted by the host.
What to do: Retire the alias. inventory.changed carries inactive and deleted units with is_active and deleted flags so you can do this ahead of time.
Messages:
units.{i} refers to a unit that is no longer sellable.updates.{i}.unit refers to a unit that is no longer sellable.
errors
| Field | Type | Description |
|---|---|---|
units.{i}
|
{"inventory_id": 31, "is_active": false} |
|
updates.{i}.unit
|
on an availability write, the same object |
UNAVAILABLE
409 There is no free unit for the whole stay, or a unit you pinned is taken. Nothing was written. Doorloom never silently swaps a pinned unit for another.
What to do: Apply errors.availability to your calendar in the same breath, then re-quote. Note its window.to is the last NIGHT, i.e. check_out minus one day.
Message: {property name} is not available for the selected dates.
errors
| Field | Type | Description |
|---|---|---|
availability
|
a per-night snapshot of the property across the stay — the same shape as an availability.changed payload, minus units[]. Absent on an update that changed the units without sending check_in and check_out |
BOOKING_CANCELLED
409 A cancelled booking is terminal. It cannot be modified or un-cancelled.
What to do: Create a new booking. Cancelling an already-cancelled booking is not an error — that stays a 200.
Message: A cancelled booking cannot be modified.
REVISION_MISMATCH
412
You sent If-Match and the booking has changed since you read it. The revision increments on every change, including host-side edits made in the Doorloom app.
What to do: Re-read the booking, re-apply your change on top, and retry. If-Match is optional; omit it to force the write.
Message: The booking was modified since you last read it.
errors
| Field | Type | Description |
|---|---|---|
current_revision
|
integer — the revision the booking is actually at |
SYNC_TOO_SOON
429 A full re-sync was requested too recently. One is allowed every 24 hours.
What to do: Wait errors.retry_after seconds — which may be most of a day. If you are catching up on missed events, use GET /events?after_sequence= instead: it has no interval and gives you exactly what you missed.
Message: A full sync was requested {time} ago; wait {n} seconds.
errors
| Field | Type | Description |
|---|---|---|
retry_after
|
integer seconds |
RATE_LIMITED
429
You exceeded one of the rate limits. The standard Retry-After and X-RateLimit-* headers are set on the response. The second message is the calendar-write limit: 10 calls per property per hour on each of PUT availability, rates and restrictions.
What to do: Back off for Retry-After seconds. Limits are per integration, so they are yours alone to manage. For the calendar-write limit, stop sending one call per date: a call takes up to 50 date ranges.
Messages:
Too many requests. Retry after {n} seconds.This property's {availability|rates|restrictions} can be updated {n} times an hour. Retry after {n} seconds, and send date ranges instead of one call per date.
errors
| Field | Type | Description |
|---|---|---|
retry_after
|
integer seconds |
NOT_FOUND
404 No such booking or property for this integration. Another integration's booking or property is not found rather than forbidden, so ids cannot be probed across partners. On a property write, a property whose coverage staff have removed is also not found.
What to do: Check the id, and check that the property is still covered.
Messages:
No such booking for this integration.No booking with that external id.No covered property with that id.
UNAUTHENTICATED
401 No API key, or a key that is not valid. Rotating your API key invalidates the previous one immediately.
What to do: Send Authorization: Bearer <your API key>.
Message: Send your integration API key as: Authorization: Bearer <key>.
NOT_INTEGRATION_TOKEN
403 The bearer token is valid but is not an integration API key — it belongs to another Doorloom token surface. Integration keys are the only credential this API accepts.
What to do: Use the API key Doorloom issued for this integration.
Message: This endpoint accepts integration API keys only.
INTEGRATION_DISABLED
403 Doorloom staff disabled this integration. No events are recorded and no API call succeeds. This is distinct from paused: a paused integration keeps full API access and only stops receiving webhooks.
What to do: Contact Doorloom.
Message: This integration has been disabled.
Responses that are not in this shape
A request that never reaches an endpoint is answered before any of the codes above can apply,
so it has no success and no code.
| Field | Type | Description |
|---|---|---|
404 with only a message
|
routing | The path does not exist, or an id in it is malformed: /bookings/abc where a number belongs. Check the path. There is no switch that turns the API off, so this never means that. |
405 with only a message
|
routing | The path exists but not with this method. |
500 with only a message
|
server | An error Doorloom did not anticipate. Retry with backoff, reusing the same Idempotency-Key on a create, and tell us if it persists. |
404 HTML, or a gateway error page
|
infrastructure | You are not reaching the application at all. Check the host. |