Best Practices

Follow these recommendations to build reliable, performant integrations with the Repull API.

Pagination

Always paginate list endpoints. Never assume a collection fits in one response.

• Use cursor-based pagination when available — it is stable across inserts and deletes.
• Fall back to page + limit for endpoints that support offset pagination.
• Keep page sizes reasonable (50-100 items). Larger pages increase latency and memory usage.
• Check the has_more field in the response to know when to stop.

Error Handling

Build resilient error handling from day one.

• Retry on 429 (rate limited) and 5xx (server error) responses with exponential backoff.
• Respect the Retry-After header when present — it tells you exactly how long to wait.
• Do not retry 400, 401, 403, or 404 errors — these indicate a problem with your request, not a transient failure.
• Cap retries at 3 attempts. If a request still fails, log it and alert your team.

Caching

Cache intelligently to reduce API calls and improve performance.

• Property data (names, amenities, photos) changes infrequently — cache for 5-60 minutes.
• Reservation data changes more often — refresh every 1-5 minutes, or rely on webhooks for real-time updates.
• Availability and pricing are time-sensitive — cache for no more than 60 seconds, or use webhooks.
• Use sync.complete webhook events to invalidate caches when a PMS sync finishes.

Webhook Reliability

Treat webhooks as the primary data flow, not just a convenience.

• Always verify the X-Connect-Webhook-Signature header using your webhook signing secret.
• Return 200 immediately, then process the event asynchronously. Slow responses cause retries.
• Make your webhook handler idempotent — the same event may be delivered more than once.
• After 10 consecutive delivery failures, Repull auto-disables the webhook. Re-enable it in the dashboard.

Sandbox First

Develop and test against sandbox before touching live data.

• Use sk_test_ API keys for all development and staging environments.
• Sandbox provides pre-seeded properties, reservations, and guests — no setup required.
• Use magic IDs to trigger specific error scenarios (see Sandbox Test Scenarios).
• Only switch to sk_live_ keys when you are confident the integration works end-to-end.

Idempotency

Protect against duplicate operations.

• Include an Idempotency-Key header on every POST, PUT, and PATCH request.
• Use UUIDs or deterministic keys derived from your business logic (e.g. create-res-{guestId}-{checkIn}).
• Keys are cached for 24 hours. Sending the same key returns the original response without re-executing the operation.