Error Handling

Travelyzer Places API uses standard HTTP codes and returns structured error messages in JSON. This guide helps you understand and resolve common errors.

Error Format

All errors follow this JSON format:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Detailed error description"
}

Field	Type	Description
`statusCode`	`number`	HTTP error code
`error`	`string`	Error type (standard HTTP name)
`message`	`string`	Human-readable error description
`retryAfter`	`number`	(Optional) Seconds to wait before retrying

Client Errors (4xx)

These errors indicate a problem with your request. They are generally not recoverable without correction.

400 Bad Request

The request is malformed or required parameters are missing.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "query parameter is required"
}

Common causes:

Cause	Example	Solution
Missing parameter	`/v1/geocoding/forward` without `query`	Add `?query=Paris`
Empty parameter	`?query=`	Provide a non-empty value
Invalid coordinates	`?lat=999&lon=999`	Use lat between -90/90, lon between -180/180

Corrected request example:

# Correct
curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Paris" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# Incorrect (missing parameter)
curl "https://places.gotravelyzer.com/v1/geocoding/forward" \
  -H "Authorization: Bearer YOUR_TOKEN"

401 Unauthorized

Authentication failed.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid token"
}

Common causes and solutions:

Message	Cause	Solution
`Missing Authorization header`	Header absent	Add `Authorization: Bearer <token>`
`Invalid token`	Malformed token	Check the token format
`Token expired`	Token expired	Request a new token
`Invalid API key`	Wrong key during exchange	Check the API Key
`Invalid API secret`	Wrong secret during exchange	Check the API Secret

Header verification:

# Correct
curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Paris" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 
# Incorrect (missing Bearer)
curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Paris" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 
# Incorrect (wrong header)
curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=Paris" \
  -H "X-API-Key: my_token"

Get a new token:

curl -X POST "https://api2.gotravelyzer.com/api-clients/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "gck_your_api_key",
    "apiSecret": "gcs_your_api_secret"
  }'

403 Forbidden

Access is denied despite valid authentication.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "API key disabled"
}

Common causes:

Message	Cause	Solution
`API key disabled`	Key disabled	Reactivate in Dashboard
`Quota exceeded`	Monthly quota exceeded	Wait for reset or upgrade
`Domain not allowed`	Domain restriction	Check restrictions
`IP not allowed`	IP restriction	Check restrictions

Actions:

Log in to the Dashboard
Check your API key status
Check configured restrictions
Contact support if necessary

404 Not Found

The requested endpoint does not exist.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Cannot GET /unknown"
}

Available endpoints:

Endpoint	Method	Description
`/v1/geocoding/forward`	GET	Forward geocoding
`/v1/geocoding/reverse`	GET	Reverse geocoding
`/v1/geocoding/autocomplete`	GET	Autocomplete
`/v1/geocoding/batch`	POST	Batch geocoding
`/health`	GET	Service status
`/sla-metrics`	GET	SLA metrics
`/sla-history`	GET	SLA history
`/coverage`	GET	Coverage by country

429 Too Many Requests

Request limit exceeded.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "retryAfter": 45
}

Handling 429:

# If you receive a 429, wait the time indicated in retryAfter
# then retry the request
 
# Check limit headers
curl -v "https://places.gotravelyzer.com/v1/geocoding/forward?query=Paris" \
  -H "Authorization: Bearer YOUR_TOKEN" 2>&1 | grep -i "x-ratelimit"

Response headers:

Header	Description
`X-RateLimit-Limit`	Limit per minute
`X-RateLimit-Remaining`	Remaining requests
`Retry-After`	Seconds until reset

See Rate Limits for more details.

Server Errors (5xx)

These errors indicate a server-side problem. They are generally temporary and recoverable with a retry.

500 Internal Server Error

Unexpected server error.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Action:

Retry the request after a few seconds
If the error persists after 3 attempts, contact support

502 Bad Gateway

Communication error with internal services.

{
  "statusCode": 502,
  "error": "Bad Gateway",
  "message": "Upstream service error"
}

Action:

Temporary error, usually resolved automatically
Retry after 2-5 seconds

503 Service Unavailable

The service is temporarily unavailable (maintenance).

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable"
}

Action:

Check the status page
Retry with exponential backoff
Service should be restored quickly

Retry Strategy

Exponential Backoff

For recoverable errors (429, 500, 502, 503), use exponential backoff:

Attempt 1: wait 1 second
Attempt 2: wait 2 seconds
Attempt 3: wait 4 seconds
Attempt 4: wait 8 seconds
...

Bash example:

#!/bin/bash
 
TOKEN="your_token"
QUERY="Paris"
MAX_RETRIES=3
 
for i in $(seq 1 $MAX_RETRIES); do
  RESPONSE=$(curl -s -w "\n%{http_code}" \
    "https://places.gotravelyzer.com/v1/geocoding/forward?query=$QUERY" \
    -H "Authorization: Bearer $TOKEN")
 
  HTTP_CODE=$(echo "$RESPONSE" | tail -1)
  BODY=$(echo "$RESPONSE" | head -n -1)
 
  if [ "$HTTP_CODE" -eq 200 ]; then
    echo "Success:"
    echo "$BODY"
    exit 0
  elif [ "$HTTP_CODE" -eq 429 ] || [ "$HTTP_CODE" -ge 500 ]; then
    WAIT=$((2 ** ($i - 1)))
    echo "Attempt $i failed (HTTP $HTTP_CODE). Retrying in ${WAIT}s..."
    sleep $WAIT
  else
    echo "Non-recoverable error (HTTP $HTTP_CODE):"
    echo "$BODY"
    exit 1
  fi
done
 
echo "Failed after $MAX_RETRIES attempts"
exit 1

Summary Table

Code	Error	Recoverable	Recommended Action
400	Bad Request	No	Fix parameters
401	Unauthorized	No	Check/renew token
403	Forbidden	No	Check permissions in Dashboard
404	Not Found	No	Check endpoint URL
429	Too Many Requests	Yes	Wait `retryAfter` seconds
500	Internal Server Error	Yes	Retry with backoff
502	Bad Gateway	Yes	Retry with backoff
503	Service Unavailable	Yes	Retry with backoff

Quick Diagnosis

# 1. Check that the API is accessible
curl "https://places.gotravelyzer.com/health"
# Expected: {"ok": true}
 
# 2. Check that your token is valid
curl "https://places.gotravelyzer.com/v1/geocoding/forward?query=test" \
  -H "Authorization: Bearer YOUR_TOKEN"
# If 401: invalid or expired token
 
# 3. Check your quotas
curl -v "https://places.gotravelyzer.com/v1/geocoding/forward?query=test" \
  -H "Authorization: Bearer YOUR_TOKEN" 2>&1 | grep -E "X-RateLimit|X-Quota"
# Shows limit headers

Support

If you encounter persistent errors:

Check the API status page
Review your logs in the Dashboard
Contact support: contact@gotravelyzer.com

Rate Limits

Understand request limits by plan.

Authentication

Properly configure JWT authentication.