Error Handling

Understand API errors and how to handle them gracefully.

Error Response Format

All API errors follow a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable error message",
    "details": {
      "field": "Additional context if available"
    }
  },
  "request_id": "req_abc123xyz"
}
Field Type Description
success boolean Always false for errors
error.code string Machine-readable error code
error.message string Human-readable description
error.details object Additional error context (optional)
request_id string Unique ID for support reference

HTTP Status Codes

2xx Success

  • 200 - Request successful
  • 201 - Resource created
  • 204 - No content (successful deletion)

4xx Client Errors

  • 400 - Bad request (invalid parameters)
  • 401 - Unauthorized (missing/invalid API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Resource not found
  • 409 - Conflict (resource already exists)
  • 422 - Unprocessable entity (validation failed)
  • 429 - Too many requests (rate limited)

5xx Server Errors

  • 500 - Internal server error
  • 502 - Bad gateway
  • 503 - Service unavailable
  • 504 - Gateway timeout

Common Error Codes

Authentication Errors

Code Status Description
MISSING_API_KEY 401 No API key provided in request headers
INVALID_API_KEY 401 The API key is invalid or has been revoked
EXPIRED_API_KEY 401 The API key has expired
INSUFFICIENT_PERMISSIONS 403 API key lacks required permissions

Validation Errors

Code Status Description
INVALID_REQUEST 400 Request body is malformed or missing required fields
INVALID_PARAMETER 400 A parameter value is invalid
MISSING_FIELD 422 A required field is missing
INVALID_DATE_FORMAT 422 Date is not in ISO 8601 format
INVALID_AIRPORT_CODE 422 Airport ICAO/IATA code not found

Booking Errors

Code Status Description
BOOKING_NOT_FOUND 404 Booking with given ID does not exist
AIRCRAFT_UNAVAILABLE 409 Selected aircraft is no longer available
BOOKING_ALREADY_CONFIRMED 409 Booking has already been confirmed
BOOKING_CANCELLED 409 Cannot modify a cancelled booking
DEPARTURE_TOO_SOON 422 Departure date is too close for booking

Rate Limiting

Code Status Description
RATE_LIMIT_EXCEEDED 429 Too many requests in the current time window
QUOTA_EXCEEDED 429 Daily/monthly request quota exceeded

Error Handling Best Practices

1. Check the status code first

Use the HTTP status code to determine the general category of error before parsing the response body.

2. Use error codes for logic

Use the error.code field for programmatic error handling, not the message string.

3. Implement retry logic

For 5xx errors and rate limiting (429), implement exponential backoff retry logic.

4. Log request IDs

Always log the request_id for debugging and when contacting support.

Example: Handling Errors

async function searchFlights(params) {
  try {
    const response = await fetch('https://booking.api.jets.partners/v1/flights/search', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(params)
    });

    const data = await response.json();

    if (!response.ok) {
      // Handle specific error codes
      switch (data.error?.code) {
        case 'INVALID_AIRPORT_CODE':
          console.error('Invalid airport:', data.error.details);
          break;
        case 'RATE_LIMIT_EXCEEDED':
          // Retry after delay
          const retryAfter = response.headers.get('Retry-After') || 60;
          await delay(retryAfter * 1000);
          return searchFlights(params);
        default:
          console.error('API Error:', data.error?.message);
      }
      throw new Error(data.error?.message || 'Unknown error');
    }

    return data;
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

Need Help?

If you encounter persistent errors or need assistance:

  • Include the request_id from the error response
  • Provide the full request and response (excluding your API key)
  • Contact support at hello@jets.partners