Docs / Error Handling

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"
  }
}

Field	Type	Description
`success`	boolean	Always `false` for errors
`error.code`	string	Machine-readable error code
`error.message`	string	Human-readable description

HTTP Status Codes

2xx Success

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

4xx Client Errors

400 - Bad request
401 - Unauthorized
403 - Forbidden
404 - Not found
409 - Conflict
422 - Unprocessable
429 - 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`	400	A required field is missing
`INVALID_FIELD`	400	A field value is invalid (wrong format, out of range, etc.)

Search Errors

Code	Status	Description
`SEARCH_FAILED`	500	Flight or empty leg search failed
`FORBIDDEN`	403	Insufficient permissions for this operation

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/api/quoting/options', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(params)
    });

    const data = await response.json();

    if (!response.ok) {
      switch (data.error?.code) {
        case 'INVALID_AIRPORT_CODE':
          console.error('Invalid airport:', data.error.details);
          break;
        case 'RATE_LIMIT_EXCEEDED':
          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