Rate Limits and Errors

The Sky Schedule REST API allows 100 requests per school per UTC day and returns at most 100 records per list request. This page covers the rate limits, how to read the rate limit headers, how pagination works, and what each error code means.

Daily rate limits

• 100 requests per school per UTC day. The counter resets at 00:00 UTC.
• The limit is per school, not per key or per IP address.
• Every request that passes the key check counts, including requests that come back 400 or 404. Requests rejected for a missing or invalid key (401) or an inactive subscription (403) don't count.
• The limit query parameter changes page size only. It doesn't raise the daily limit.
• The MCP server has its own counters (1,000 requests and 200 write tool calls per day). MCP traffic never uses up your REST requests, and REST traffic never uses up MCP requests.

Rate limit headers

Successful responses, 404 responses, and 429 responses include three headers:

Successful responses repeat the same numbers in the body under meta.rateLimit.

curl -si "https://app.skyschedule.io/api/v1/squawks?limit=1" \
  -H "Authorization: Bearer $SKYSCHEDULE_API_KEY"

HTTP/2 200
content-type: application/json
x-ratelimit-limit: 100
x-ratelimit-remaining: 87
x-ratelimit-reset: 2026-10-09T00:00:00.000Z

When you hit the limit

The API returns 429 until the reset time:

{ "error": "Daily rate limit exceeded." }

Don't retry in a loop. Every retry gets the same answer until X-RateLimit-Reset. A few ways to stay well under 100 a day:

• Cache the customer and instructor rosters. They change far less often than the schedule.
• Pull completed flights once a day for the previous day, not every few minutes.
• Ask for limit=100 when you need a lot of records, instead of several small pages.

Pagination

List endpoints take an optional limit query parameter.

• Default: 50 records when limit is left out.
• Maximum: 100. A higher value is rejected with 400, not quietly lowered.
• limit must be a whole number of 1 or more. 0, negative numbers, decimals, and text are rejected with 400.
• meta.pageSize is the page size the server used. meta.count is how many records came back.

There is no cursor or offset. Each list returns the first records in its sort order, up to limit. When meta.count equals meta.pageSize, there may be more records than you received.

• For reservations and completed flights, get more records by asking for smaller date ranges with from and to, for example one week per request.
• Customers, instructors, maintenance lists, and comments have no date filter, so a request returns at most the first 100 records in the order below.

Query parameters an endpoint doesn't use are ignored. For example, from on /customers has no effect.

Error format

Every error has the same body, a single error string:

{ "error": "Invalid from date. Use YYYY-MM-DD." }

HTTP status codes

400 and 500 responses don't carry the rate limit headers. Read the remaining count from your last successful response.