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.

Error envelope

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."
  }
}
FieldMeaning
request_idCorrelation identifier to retain in safe operational logs and support requests.
error.codeStable machine-readable code for branching and alerting.
error.messageSafe human-readable explanation. Do not branch on the message text.

Availability item errors

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.

Error reference

CodeHTTP or resultMeaningRecommended action
PARTNER_UNAUTHORIZED401Credentials, bearer token, or partner-token claims are invalid or expired.Authenticate again if the access token expired; otherwise correct the credentials.
PARTNER_DISABLED403Bolt disabled the partner account.Stop automated retries and contact Bolt partner support.
CONNECTION_NOT_FOUND404The connection does not exist or is not visible to the authenticated partner.Refresh your connection list and verify the stored connection ID.
CONNECTION_NOT_ACTIVE409The operation requires an ACTIVE connection.Read the connection and wait for or resolve its current state before retrying.
CONNECTION_ALREADY_ACCEPTED409An active connection was accepted again with a different external property ID.Keep the original external property ID or coordinate a correction with Bolt.
CONNECTION_REJECTED409The requested action cannot be performed because the connection is rejected.Wait for the property to create a new connection request.
ROOM_NOT_FOUND404A 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_FOUNDAvailability itemNo 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_ID409The 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_CONFLICT409 mapping response or availability itemThe 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_DATEAvailability itemA date is not a real YYYY-MM-DD calendar date.Correct the date and retry the item with a new key.
INVALID_DATE_RANGEAvailability itemDate 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_AVAILABILITYAvailability itemAvailability is not a non-negative integer or exceeds the room's total inventory.Send an integer from 0 through total_units.
TOO_MANY_UPDATES413The request expands beyond 5,000 room-date entries.Split the logical changes into smaller batches with different keys.
IDEMPOTENCY_KEY_REQUIRED400The availability request omitted Idempotency-Key.Add a stable key for the logical batch and retry.
IDEMPOTENCY_KEY_REUSED409The 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_PROGRESS409A request with this connection and idempotency key is still processing.Wait, then retry the same canonical payload with the same key.
RATE_LIMIT_EXCEEDED429The current auth, reservation, or availability request window is exhausted.Honor retry-after and use backoff.
RESERVATION_EVENT_NOT_FOUND404The 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_FOUND404The reservation is not visible on the active connection.Verify the connection and reservation ID from the event.
INVALID_ACKNOWLEDGEMENT400The acknowledgement status is not PROCESSED.Acknowledge only after inventory processing and absolute availability update succeed.
VALIDATION_ERROR400The request body, path, or query parameters do not match the endpoint schema.Correct the request; repeating it unchanged will not help.
INTERNAL_ERROR500Bolt 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.

Retryable conditions

  • 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.

Correct before retrying

  • 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.
Errors | Bolt Partner API