Error Codes

This document lists all error codes that Bundleport APIs can return. Each error includes the HTTP status code, error code, description, and recommended action.

Authentication Errors

UNAUTHORIZED

HTTP Status: 401 Unauthorized

Description: Invalid or missing API key.

Response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Solution:

• Verify your API key is correct
• Check the Authorization header format: ApiKey YOUR_KEY
• Ensure the key hasn't been revoked
• Verify you're using the correct environment (sandbox vs production)

FORBIDDEN

HTTP Status: 403 Forbidden

Description: API key doesn't have required permissions (scopes).

Response:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have required scope: hotels:book"
  }
}

Solution:

• Check your API key scopes in the dashboard
• Request additional scopes if needed
• Use a different API key with appropriate permissions

Validation Errors

VALIDATION_ERROR

HTTP Status: 400 Bad Request

Description: Request payload doesn't match the API schema.

Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {
      "field": "stay.checkIn",
      "reason": "Date must be in YYYY-MM-DD format"
    }
  }
}

Solution:

• Fix the validation errors in the request
• Check field types and formats
• Ensure required fields are present
• Review the API schema documentation

INVALID_DESTINATION

HTTP Status: 400 Bad Request

Description: Destination code is invalid or not supported.

Response:

{
  "error": {
    "code": "INVALID_DESTINATION",
    "message": "Destination code 'XXX' is not valid"
  }
}

Solution:

• Use valid destination codes (IATA codes for airports, city codes, etc.)
• Check the Content API for available destinations
• Verify the destination code format

INVALID_DATE_RANGE

HTTP Status: 400 Bad Request

Description: Check-in or check-out date is invalid.

Response:

{
  "error": {
    "code": "INVALID_DATE_RANGE",
    "message": "Check-out date must be after check-in date"
  }
}

Solution:

• Ensure check-out date is after check-in date
• Use valid date format (YYYY-MM-DD)
• Check minimum stay requirements
• Verify dates are not in the past

INVALID_OCCUPANCY

HTTP Status: 400 Bad Request

Description: Occupancy configuration is invalid.

Response:

{
  "error": {
    "code": "INVALID_OCCUPANCY",
    "message": "Maximum occupancy exceeded for room type"
  }
}

Solution:

• Check room maximum occupancy
• Ensure children ages are provided when children > 0
• Verify occupancy matches room capacity

Business Logic Errors

NO_AVAILABILITY

HTTP Status: 200 OK (with empty results) or 404 Not Found

Description: No hotels available for the search criteria.

Response:

{
  "error": {
    "code": "NO_AVAILABILITY",
    "message": "No hotels found matching your criteria"
  }
}

Solution:

• Adjust search criteria (dates, destination, filters)
• Try different date ranges
• Remove restrictive filters
• Check if destination is available

PRICE_CHANGED

HTTP Status: 400 Bad Request

Description: Price changed between quote and booking.

Response:

{
  "error": {
    "code": "PRICE_CHANGED",
    "message": "Price has changed. Please recheck availability.",
    "details": {
      "originalPrice": 150.00,
      "newPrice": 165.00
    }
  }
}

Solution:

• Recheck availability using the quote endpoint
• Present updated price to user
• Book with the new price if acceptable

BOOKING_FAILED

HTTP Status: 400 Bad Request or 500 Internal Server Error

Description: Booking could not be completed.

Response:

{
  "error": {
    "code": "BOOKING_FAILED",
    "message": "Booking failed: Room no longer available",
    "details": {
      "provider": "SUPPLIER_1",
      "reason": "INVENTORY_EXHAUSTED"
    }
  }
}

Solution:

• Search again for alternative options
• Try a different room type or board
• Check if hotel is still available
• Contact support if issue persists

OPTION_EXPIRED

HTTP Status: 400 Bad Request

Description: The optionRefId has expired or is no longer valid.

Response:

{
  "error": {
    "code": "OPTION_EXPIRED",
    "message": "Option reference has expired. Please search again."
  }
}

Solution:

• Perform a new search
• Quote the option immediately before booking
• Don't store optionRefId for extended periods

INVALID_BOOKING_REFERENCE

HTTP Status: 404 Not Found

Description: Booking reference not found or invalid.

Response:

{
  "error": {
    "code": "INVALID_BOOKING_REFERENCE",
    "message": "Booking with ID 'xxx' not found"
  }
}

Solution:

• Verify the booking ID is correct
• Check if booking exists in your account
• Ensure you're querying the correct environment

Rate Limiting

RATE_LIMIT_EXCEEDED

HTTP Status: 429 Too Many Requests

Description: Too many requests in a short period.

Response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 60 seconds."
  }
}

Headers:

Retry-After: 60
X-RateLimit-Limit-Minute: 600
X-RateLimit-Remaining-Minute: 0

Solution:

• Wait for the time specified in Retry-After header
• Implement exponential backoff
• Reduce request frequency
• Consider caching responses
• Contact support to increase limits if needed

Server Errors

INTERNAL_SERVER_ERROR

HTTP Status: 500 Internal Server Error

Description: An unexpected error occurred on the server.

Response:

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal error occurred. Please try again later."
  }
}

Solution:

• Retry the request with exponential backoff
• If issue persists, contact support
• Check status page for known issues

SERVICE_UNAVAILABLE

HTTP Status: 503 Service Unavailable

Description: Service is temporarily unavailable.

Response:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service is temporarily unavailable. Please try again later."
  }
}

Solution:

• Retry after a short delay
• Check status page
• Implement circuit breaker pattern

GATEWAY_TIMEOUT

HTTP Status: 504 Gateway Timeout

Description: Request timed out waiting for a response from upstream service.

Response:

{
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "Request timed out. Please try again."
  }
}

Solution:

• Retry the request
• Reduce request complexity if possible
• Check supplier status

Supplier Errors

SUPPLIER_ERROR

HTTP Status: 502 Bad Gateway or 500 Internal Server Error

Description: Error from supplier integration.

Response:

{
  "error": {
    "code": "SUPPLIER_ERROR",
    "message": "Supplier returned an error",
    "details": {
      "supplier": "SUPPLIER_1",
      "supplierErrorCode": "INVENTORY_UNAVAILABLE"
    }
  }
}

Solution:

• Try a different supplier if multiple are configured
• Retry the request
• Check supplier-specific error details
• Contact support if issue persists

SUPPLIER_TIMEOUT

HTTP Status: 504 Gateway Timeout

Description: Supplier did not respond within timeout period.

Response:

{
  "error": {
    "code": "SUPPLIER_TIMEOUT",
    "message": "Supplier did not respond in time",
    "details": {
      "supplier": "SUPPLIER_1"
    }
  }
}

Solution:

• Request may have partial results from other suppliers
• Check tracing.accessSpans for supplier status
• Retry if needed

Content API Errors

CONTENT_NOT_FOUND

HTTP Status: 404 Not Found

Description: Requested content (hotel, room, destination) not found.

Response:

{
  "error": {
    "code": "CONTENT_NOT_FOUND",
    "message": "Hotel with code '12345' not found"
  }
}

Solution:

• Verify the content code is correct
• Check if content exists for your connection
• Use Content API to list available content

INVALID_CONNECTION_CODE

HTTP Status: 400 Bad Request

Description: Connection code is invalid or not configured.

Response:

{
  "error": {
    "code": "INVALID_CONNECTION_CODE",
    "message": "Connection code 'XXX' is not valid"
  }
}

Solution:

• Verify connection code in dashboard
• Check connection is active
• Ensure connection code matches your account

Error Handling Best Practices

1. Always check response status before processing
2. Log errors with full context for debugging
3. Implement retry logic for transient errors (5xx, 429)
4. Don't retry client errors (4xx) without fixing the request
5. Provide user-friendly messages based on error codes
6. Monitor error rates to detect integration issues

Next Steps

• Error Handling Guide - Learn how to handle errors gracefully
• Rate Limits - Understand rate limiting
• Connect Hotels Overview - Start using the API