Error Handling, Rate Limits & Best Practices

A production-grade integration should handle API errors gracefully, respect rate limits, and follow caching and performance best practices. This article covers all three topics to help you build a reliable, performant integration.

Error Response Format

When an API call fails, the response body contains a structured error:

{
  "message": "Description of the error",
  "status": 400
}

Some error responses include additional detail:

{
  "error": {
    "message": "Detailed error description",
    "status": 400
  }
}

*

HTTP Status Codes

*

Error Handling by Endpoint

Authentication Errors (401)

The most common cause is an expired signature. Implement auto-refresh logic (see Authentication & API Signatures) and retry the failed request with the new signature.

async function apiCall(method, endpoint, data, correlationId) {  let signature = await signatureManager.getSignature();
try {    return await makeRequest(method, endpoint, data, signature, correlationId);  } catch (error) {    if (error.status === 401) {      // Signature may have expired — force refresh and retry once      signature = await signatureManager.forceRefresh();      return await makeRequest(method, endpoint, data, signature, correlationId);    }    throw error;  }}

Search Errors (No Results)

A hotel search may return zero results without an error status. This isn't an API failure — it means no properties matched your criteria. Handle this by:

• Suggesting nearby locations or broader date ranges.
• Relaxing filters (e.g., remove star rating or price constraints).
• Displaying a friendly "no results" message.

Availability Errors

Rooms may become unavailable between the search and the availability check. If the availability response returns an empty array:

• Inform the user that the room is no longer available.
• Suggest re-searching or checking a different hotel.

Pricing Errors

If the pricing confirmation fails or the token is invalid:

• Re-run the availability check to get a fresh availability token.
• Confirm the price again to get a new pricing token.
• Notify the guest if the price has changed.

Booking Errors

Booking failures can occur due to expired pricing tokens, sold-out rooms, or invalid guest data. Always:

• Validate guest information client-side before submitting.
• Check pricing token freshness (10-minute window) before booking.
• Display a clear error message and offer the option to retry.

Rate Limits

The Xeni Hotels API enforces rate limits to ensure fair usage and system stability.

Rate Limit Headers

Rate limit information is included in response headers:

Handling 429 Responses

When you receive a 429 response:

1. Stop making requests immediately.
2. Wait until the rate limit window resets (check the RateLimit-Reset header).
3. Resume with normal request patterns.

*

Caching Recommendations

Intelligent caching reduces API calls, improves response times, and stays within rate limits. Here are recommended cache durations by data type:

Cache Key Strategy

Generate unique cache keys from the request parameters. A common approach:

// JavaScriptimport crypto from 'crypto';
function generateCacheKey(prefix, params) {  const hash = crypto.createHash('md5')    .update(JSON.stringify(params))    .digest('hex');  return cache:${prefix}:${hash};}
// Examples:generateCacheKey('location', { query: 'miami' });// → "cache:location:3f8c9a2b..."
generateCacheKey('search', { lat: 25.76, long: -80.19, checkIn: '2025-06-01', checkOut: '2025-06-05' });// → "cache:search:7d2e1f4a..."

*

Timeout Configuration

Set appropriate request timeouts for each API call. Our recommendations:

Hotel search and availability checks may take longer because they query multiple suppliers in real time.

*

Retry Strategy

Not all errors are permanent. Use a retry strategy with exponential backoff for transient failures:

Example: Retry with Exponential Backoff

async function apiCallWithRetry(fn, maxRetries = 3) {  for (let attempt = 0; attempt <= maxRetries; attempt++) {    try {      return await fn();    } catch (error) {      const status = error.response?.status;
// Don't retry client errors (except 401 and 429)      if (status && status >= 400 && status < 500 && status !== 401 && status !== 429) {        throw error;      }
if (attempt === maxRetries) throw error;
const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s      await new Promise(resolve => setTimeout(resolve, delay));    }  }}

*

Production Readiness Checklist

Before going live, verify your integration meets these criteria:

*

Getting Help

If you encounter issues that aren't resolved by this documentation:

• Check the error message: The API returns descriptive error messages that usually point to the root cause.
• Verify in UAT first: Test your request against the UAT environment to isolate the issue.
• Contact support: Reach out to your Xeni account representative with the following details: