Best Practices
This page covers performance optimization and user experience patterns for building high-quality integrations with the Mobility API.
Performance Optimization
Search requests trigger real-time aggregation across multiple providers, which means they are the most expensive operations in terms of latency and server load. Cache search results locally for short periods (up to 5 minutes) to avoid redundant requests when users navigate back to results they have already seen. Implement request debouncing on user-driven inputs like location or date changes so that rapid modifications do not fire multiple simultaneous searches.
Fetch offer details only when the user explicitly requests them — do not preload details for every offer in a search result set. Similarly, only call the prebook endpoint when the user is ready to proceed to checkout, since prebooking locks inventory and has a limited validity window. When using paginated endpoints, choose a page size that balances between too many requests (small pages) and unnecessarily large payloads (large pages); 20-50 items per page works well for most use cases.
Set appropriate client-side timeouts for each operation type. Searches can take up to 20 seconds due to multi-provider aggregation, so a 25-second timeout is recommended. Booking creation may take up to 15 seconds and should have a 30-second timeout. For other operations like offer details and prebook, 10-15 seconds is sufficient. When retrying after server errors, use exponential backoff (1s, 2s, 4s, 8s) with a maximum of 3-5 attempts to avoid overwhelming the API. See Error Handling for the complete retry strategy.
Rate Limits
The API enforces rate limits to ensure fair usage and platform stability. Limits are applied per API key using a sliding window algorithm.
Default Limits
| Context | Limit | Window |
|---|---|---|
| Standard API key | 100 requests | 60 seconds |
| Custom (per key) | Configurable | Configurable |
Organization administrators can configure custom rate limits per API key in the Dashboard Portal. Contact your account manager for higher limits.
Rate Limit Headers
Every API response includes rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Handling 429 Responses
When you exceed the rate limit, the API returns a 429 Too Many Requests status. Implement exponential backoff when retrying:
# Check rate limit headers in the response
curl -i -X POST https://adapt2move.de/mobility-api/v2/cars \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"pickup": {"type": "coordinates", "coordinates": {"latitude": 52.52, "longitude": 13.405}}, "dates": {"start": "2026-12-15T10:00:00Z", "end": "2026-12-20T10:00:00Z"}}'
# Response headers include:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 97
# X-RateLimit-Reset: 1734567890
Monitor the X-RateLimit-Remaining header proactively. Throttle your requests before hitting the limit rather than relying on retry logic after receiving a 429.
User Experience Patterns
Loading States and Search Feedback
Because multi-provider searches can take anywhere from 1 to 20 seconds, always display a loading indicator or progress spinner during search operations. Consider showing a message that explains results are being gathered from multiple providers — this sets appropriate expectations and reduces perceived wait times. Allow users to cancel long-running searches if they want to modify their criteria.
Offer Freshness
Offers reflect real-time availability and pricing. Prices can change at any moment unless a prebooking has been created, and availability shifts as other users book similar offers. Do not cache search results for longer than 5 minutes, and consider showing a "results may have changed" indicator if the user returns to stale results. When an offer expires during the booking flow, guide the user back to search with a clear message rather than showing a generic error.
Policy Display
Display cancellation policies, terms, and conditions before the user commits to a booking. Highlight non-refundable bookings prominently so users are not surprised later. Show refund amounts clearly when applicable. For bookings with restrictive policies, require explicit user acceptance before proceeding to ensure informed consent.
Booking Confirmation
After a successful booking, display the booking status (CONFIRMED, PENDING, or FAILED) clearly in your UI. Show the confirmation number and voucher details prominently, along with clear next steps for the user. Note that the Adapt2Move platform sends confirmation and cancellation emails automatically — if you prefer to handle these yourself, contact our developer team to opt out.