Errors

Overview

SkyMatch uses standard HTTP status codes. When a request fails, the response body always includes a code and message field to help you debug.

{
  "error": {
    "code": "invalid_params",
    "message": "Missing required parameter: lat"
  }
}

Status codes

Status	Code	Meaning
`400`	`invalid_params`	Missing or malformed query parameters
`401`	`invalid_key`	API key is missing or invalid
`429`	`rate_limited`	Monthly request limit reached for your plan
`429`	`too_many_requests`	Too many requests in a short period — slow down and retry after a minute
`500`	`server_error`	Something went wrong on our end — please retry

Handling errors

Node.js

const response = await fetch('https://api.skymatch.uk/v1/booking-confidence?...', {
  headers: { 'X-API-Key': process.env.SKYMATCH_API_KEY }
});

if (!response.ok) {
  const error = await response.json();
  console.error(`SkyMatch error [${error.error.code}]: ${error.error.message}`);
}

const data = await response.json();

Rate limiting

When you exceed your plan’s monthly request limit, all requests return a 429 response with code rate_limited until the next billing cycle. There is also a short-term limit of 120 requests per minute per API key. Requests over it return 429 with code too_many_requests; wait a minute and retry. Every request that passes authentication counts toward your monthly limit, including ones that return an error.

You can monitor your usage via the dashboard (Starter and Growth plans). If you’re regularly hitting limits, consider upgrading your plan or contact us to discuss a custom allowance.

Retries

For 500 errors, we recommend retrying with exponential backoff:

async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 500) return res;
    await new Promise(r => setTimeout(r, Math.pow(2, i) * 500));
  }
  throw new Error('SkyMatch request failed after retries');
}

Getting started

API Endpoints

Reference

Overview

Status codes

Handling errors

Rate limiting

Retries