> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skymatch.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> How SkyMatch handles and returns 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.

```json theme={null}
{
  "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    |
| `500`  | `server_error`   | Something went wrong on our end — please retry |

## Handling errors

```javascript Node.js theme={null}
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 until the next billing cycle.

<Tip>
  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.
</Tip>

## Retries

For `500` errors, we recommend retrying with exponential backoff:

```javascript theme={null}
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');
}
```