v4/Reference

Response Codes

Mosler responses carry two layers of status, and it helps to read them separately:

The HTTP status code — the transport-level outcome (did the request reach the right place and authenticate?).
An application code in the JSON body — the business outcome (what happened to the booking, key, or device?).

A request can return HTTP 200/202 and still describe a domain result through the body code. Always branch on both.

HTTP status codes

HTTP	Meaning	When you'll see it
`200`	OK	Synchronous read succeeded (e.g. retrieving access, listing events).
`202`	Accepted	A webhook event was accepted for asynchronous processing. Body carries `eventId`.
`400`	Bad Request	Malformed payload or invalid field values.
`401`	Unauthorized	Missing or invalid `apikey` header.
`404`	Not Found	No resource for the given `referenceId`/`eventId` in your company.
`409`	Conflict	Duplicate resource — e.g. a `referenceId` that already exists.
`429`	Too Many Requests	Client is being rate-limited. See Rate Limits.
`500`	Internal Server Error	Unexpected server-side failure. Safe to retry idempotent calls with backoff.

Asynchronous calls: A 202 means received, not done. The booking still has to clear the queue and provision a credential. Track the real outcome through the event's lifecycle status — see Event Lifecycle.

Body response shape

Most endpoints return a consistent envelope. The exact keys vary by endpoint, but the status-bearing fields are stable:

Field	Type	Description
`error`	`boolean`	`true` when the operation failed. Branch on this first.
`code`	`number`	Application status code (see tables below).
`message`	`string`	Human-readable description of the `code`.
`data`	`object \| array`	The result payload, present on success.

{
    "error": false,
    "code": 7005,
    "message": "Successfully fetched Ekeys for Booking.",
    "data": [
        /* … */
    ]
}

Booking codes (7000–7999)

These are the codes you'll meet most often on the v4 booking and access endpoints.

Success

`code`	`message`
`7000`	Successfully created Booking.
`7001`	Successfully updated Booking.
`7002`	Successfully deleted Booking.
`7003`	Successfully fetched Bookings.
`7004`	Successfully freezed Booking.
`7005`	Successfully fetched Ekeys for Booking.

Client errors

`code`	`message`	Typical fix
`7400`	Invalid Data Provided.	Check required fields and value formats in the payload.
`7401`	Invalid Reference Id Provided.	The `referenceId` doesn't match a booking in your company.
`7402`	Reference Id already exists.	Use a unique `referenceId`, or send `BOOKING_UPDATE`.
`7403`	Ekey access not supported.	The mapped lock can't issue e-keys; use passcode or card.
`7404`	No upcoming booking found.	No active/future booking for the lookup.
`7405`	Access Type not supported.	Requested credential type isn't available for this device.

Server errors

`code`	`message`
`7500`	Failed to create Booking.
`7501`	Failed to update Booking.
`7502`	Failed to delete Booking.
`7503`	Failed to fetch Booking.
`7504`	Failed to create key.
`7507`	Unable to update booking.
`7508`	Failed to create key for updated booking.

Server-error codes (75xx) indicate the request was valid but Mosler couldn't complete it. These are safe to retry with exponential backoff; if they persist, capture the eventId/referenceId and contact support.

Location & inventory codes

Returned by the location-mapping endpoints (Mapping Locations).

`code`	`message`
`2400`	Site not found.
`2401`	Building not found.
`2402`	Floor not found.
`2403`	Room not found.
`2404`	No Lock Found

Event lifecycle statuses

These are not numeric codes — they're the status strings on an event, returned by the event endpoints. They tell you where an asynchronous booking is in the pipeline:

Status	Meaning
`RECEIVED`	Accepted by the webhook service; not yet queued.
`QUEUED`	Published to the queue; awaiting the worker.
`PROCESSING`	Worker is executing business logic.
`COMPLETED`	Booking processed and access provisioned.
`FAILED`	Processing failed after retries — see `message`.
`DEAD_LETTER`	Permanently failed after 3 attempts; needs manual intervention.
`DUPLICATE`	A matching event was already received; stored for audit only.

Full lifecycle semantics and retry behaviour live in Event Lifecycle.

How to handle codes in your integration

Branch on error first, then inspect code for the specific reason.
Treat 4xx/74xx as terminal — retrying without changing the request won't help. Fix the payload or reference.
Treat 5xx/75xx as transient — retry idempotent operations with exponential backoff.
Never key off message text — the human-readable strings can change. Match on the numeric code and the status enum instead.