Partner API V1
Errors
Use the stable error code for program logic, the HTTP status for broad handling, and the request ID when investigating a failure with Bolt. Messages are human-readable and may become more specific over time.
Request-level failures use one JSON envelope. Bolt also returns the request ID in the x-request-id response header.
Error response
{
"request_id": "req_example",
"error": {
"code": "CONNECTION_NOT_ACTIVE",
"message": "The connection is not active."
}
}| Field | Meaning |
|---|---|
request_id | Correlation identifier to retain in safe operational logs and support requests. |
error.code | Stable machine-readable code for branching and alerting. |
error.message | Safe human-readable explanation. Do not branch on the message text. |
Valid availability entries can succeed while other entries fail. In that case, the HTTP 200 batch response contains an errors array instead of the request-level error object.
Partial-success response
{
"request_id": "req_example",
"status": "PARTIALLY_PROCESSED",
"accepted": 2,
"rejected": 1,
"errors": [
{
"index": 2,
"code": "ROOM_MAPPING_NOT_FOUND",
"message": "No room mapping exists for CM_ROOM_999."
}
]
}Item error indexes refer to the original zero-based
updates array. Accepted totals count applied expanded entries. Rejected totals count expanded entries when possible; a structurally invalid input counts once because it cannot be expanded.| Code | HTTP or result | Meaning | Recommended action |
|---|---|---|---|
PARTNER_UNAUTHORIZED | 401 | Credentials, bearer token, or partner-token claims are invalid or expired. | Authenticate again if the access token expired; otherwise correct the credentials. |
PARTNER_DISABLED | 403 | Bolt disabled the partner account. | Stop automated retries and contact Bolt partner support. |
CONNECTION_NOT_FOUND | 404 | The connection does not exist or is not visible to the authenticated partner. | Refresh your connection list and verify the stored connection ID. |
CONNECTION_NOT_ACTIVE | 409 | The operation requires an ACTIVE connection. | Read the connection and wait for or resolve its current state before retrying. |
CONNECTION_ALREADY_ACCEPTED | 409 | An active connection was accepted again with a different external property ID. | Keep the original external property ID or coordinate a correction with Bolt. |
CONNECTION_REJECTED | 409 | The requested action cannot be performed because the connection is rejected. | Wait for the property to create a new connection request. |
ROOM_NOT_FOUND | 404 | A mapping references a Bolt room outside the connected property or a room that cannot be resolved. | List rooms again and submit an ID from that connection. |
ROOM_MAPPING_NOT_FOUND | Availability item | No saved mapping matches the supplied external room ID. | Save or correct the mapping, then submit the corrected item with a new idempotency key. |
DUPLICATE_EXTERNAL_ROOM_ID | 409 | The external room ID is already mapped to another Bolt room in the connection. | Use a unique external room ID for each Bolt room. |
ROOM_AVAILABILITY_SOURCE_CONFLICT | 409 mapping response or availability item | The room has an iCal URL or is already managed by another active channel-manager connection. | Do not retry unchanged. Clear iCal or disconnect the other active manager in Bolt first. |
INVALID_DATE | Availability item | A date is not a real YYYY-MM-DD calendar date. | Correct the date and retry the item with a new key. |
INVALID_DATE_RANGE | Availability item | Date and range fields conflict, a range is incomplete or reversed, or a date is past or beyond the horizon. | Send either date or an inclusive from/to pair within the allowed horizon. |
INVALID_AVAILABILITY | Availability item | Availability is not a non-negative integer or exceeds the room's total inventory. | Send an integer from 0 through total_units. |
TOO_MANY_UPDATES | 413 | The request expands beyond 5,000 room-date entries. | Split the logical changes into smaller batches with different keys. |
IDEMPOTENCY_KEY_REQUIRED | 400 | The availability request omitted Idempotency-Key. | Add a stable key for the logical batch and retry. |
IDEMPOTENCY_KEY_REUSED | 409 | The key has already been used with a different canonical payload. | Restore the original payload for a replay or use a new key for a different batch. |
IDEMPOTENCY_REQUEST_IN_PROGRESS | 409 | A request with this connection and idempotency key is still processing. | Wait, then retry the same canonical payload with the same key. |
RATE_LIMIT_EXCEEDED | 429 | The current auth, reservation, or availability request window is exhausted. | Honor retry-after and use backoff. |
RESERVATION_EVENT_NOT_FOUND | 404 | The event is not visible to this partner or its connection is no longer active. | Do not infer another partner's data; refresh pending events. |
RESERVATION_NOT_FOUND | 404 | The reservation is not visible on the active connection. | Verify the connection and reservation ID from the event. |
INVALID_ACKNOWLEDGEMENT | 400 | The acknowledgement status is not PROCESSED. | Acknowledge only after inventory processing and absolute availability update succeed. |
VALIDATION_ERROR | 400 | The request body, path, or query parameters do not match the endpoint schema. | Correct the request; repeating it unchanged will not help. |
INTERNAL_ERROR | 500 | Bolt could not complete the request because of an unexpected server error. | Retry with backoff; preserve the same availability idempotency key and provide request_id if the error persists. |
- For HTTP 429, wait for
retry-after, add jitter, and reduce concurrency. - For HTTP 500 or a network timeout, retry with exponential backoff. Availability retries must use the same idempotency key and canonical payload because the first request may have succeeded.
- For an in-flight idempotency conflict, wait before replaying the same key and payload.
- For an expired bearer token, authenticate again and retry the original request with the new token.
- Validation, date, availability, mapping, and duplicate-ID failures require a corrected request.
- A room-source conflict requires the property to clear its iCal URL or disconnect the other active channel manager before a retry.
- A PAUSED, REJECTED, or DISCONNECTED connection cannot receive room or availability writes. Repeating the request does not change its state.
- A disabled partner must stop automated requests and contact Bolt.
Keep secrets out of diagnostics
A support report may include
request_id, the endpoint, HTTP status, error code, connection ID, and timestamp. Never include the client secret, bearer token, full Authorization header, or guest and payment data.