Troubleshooting

Common issues, error codes, and resolution steps for integration problems.

HTTP Error Codes

When Hotelinking makes API calls to your system, it may receive error responses. Here are the most common HTTP status codes and how to resolve them.

Code	Meaning	Resolution
400	Bad Request	Check request parameters and body format. Verify date formats are ISO 8601.
401	Unauthorized	Verify API credentials. Check if tokens have expired.
403	Forbidden	Confirm API key has required permissions. Check IP allowlisting.
404	Not Found	Verify endpoint URL is correct. Check that the resource exists.
408	Request Timeout	Reduce date range. Check if the API server is responsive.
429	Too Many Requests	Rate limit exceeded. Hotelinking will automatically retry with backoff.
500	Internal Server Error	Server-side issue on the partner API. Check partner system status.
502/503	Bad Gateway / Unavailable	Partner API is temporarily down. Will retry automatically.

Circuit Breaker

Hotelinking implements a circuit breaker pattern to protect both your system and ours from cascading failures. When an integration consistently fails, the circuit breaker trips to prevent unnecessary load on a failing endpoint.

How it works

After 5 consecutive failures, the circuit breaker trips for the affected brand + integration pair
When open, no API calls are made -- this prevents overwhelming a failing system
After the backoff period expires, one test request is allowed (half-open state)
On success: circuit resets and normal operation resumes
On failure: circuit stays open with increased backoff

Backoff schedule

1 min→5 min→15 min→1 hour

Health States

Each brand + integration pair has a health status that reflects the recent success rate of API calls. The health status is updated automatically after every execution.

Healthy

0-2 consecutive failures. Normal operation. All scheduled executions proceed as configured.

Degraded

3-4 consecutive failures. Still operating but monitored closely. Alerts may be triggered.

Unhealthy

5+ consecutive failures. The circuit breaker has tripped. No API calls are made until the backoff period expires.

Circuit Open

Actively blocked and waiting for the backoff period to expire. One test request will be allowed when the timer elapses.

Rate Limiting

Hotelinking is designed to respect your API's rate limits and avoid overloading partner systems.

429 responses and Retry-After headers are respected automatically
Default concurrency: 1 request at a time per brand per sync type
Batch operations use configurable concurrency, typically 5-10 parallel requests

If your API has specific rate limits, let us know during onboarding. We can configure per-integration concurrency limits and request spacing to stay within your thresholds.

Common Issues

Empty responses

Check date range parameters -- some APIs require both dateFrom and dateTo
Verify the root_path in parser config matches your response structure
Confirm the endpoint returns data for the requested date range

Authentication failures

Check if credentials have expired or been rotated
Verify the correct auth method is configured -- auto-detection may pick the wrong method if the config structure is ambiguous
For OAuth: check that token_url is accessible and client_id/ client_secret are correct

Timeout issues

Reduce date range -- use 1-day or 1-week ranges instead of months
Check if the partner API has slow response times
Default timeout: 30 seconds for standard calls, 120 seconds for batch operations

Field mapping mismatches

Use debug mode to see raw response vs parsed output side by side
Check that root_path points to the correct array in your response
Verify nested array source_path matches your response structure
Check value maps if status or board type codes are not translating correctly

Missing guest data

Verify your API includes guest information in the reservation response
Check if flatten_guests: true is needed -- guests may be nested under stays rather than at the reservation level
Ensure dedupe_guests_by is not removing valid guests with different roles but the same identifier

If you are seeing data in your raw API response but it disappears after parsing, the most common cause is an incorrect root_path or source_path configuration. Use debug mode to compare the raw response against the parsed output at each step.

Execution Logs

Every execution is logged with detailed step-by-step results. Logs are available for review through your Hotelinking contact or via the monitoring API.

What logs include

Step name -- which processing step ran (fetch, parse, normalize, transform, deliver)
Duration -- how long each step took in milliseconds
Record count -- how many records entered and exited each step
Errors -- detailed error messages for any step that failed

Dead letter queue

Failed executions are stored in the dead letter queue for manual inspection and retry. Each entry includes the full execution context, input data, and error details so the issue can be diagnosed and the execution replayed.