Errors and rate limits

The Clearskies API is in beta and available on request. To turn it on for your workspace, email support@clearskies.cc.

Errors

A failed request returns ok: false and an error:

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "filters[0].op \"contains\" is not an operator \"createdAt\" accepts. Valid operators: equal, notEqual, before, after, isEmpty, isNotEmpty."
  },
  "requestId": "0199f2b0-7c41-7a3e-9d6c-2f5a1b8e4c07"
}

Branch on code. The message is written for a person to read, and its wording changes over time.

Code	Status	What to do
`BAD_REQUEST`	400	Fix the request. The message names the member at fault and what it accepts.
`UNAUTHORIZED`	401	Check the key. See Authentication.
`TENANT_BLOCKED`	403	Contact support.
`NOT_FOUND`	404	Check the URL. From a call transcript, it also means no call has that `id`, or the key can’t read that call; see Authentication.
`RATE_LIMITED`	429	Wait `Retry-After` seconds, then retry.
`INTERNAL_ERROR`	500	Contact support with the `requestId`.
`SERVICE_UNAVAILABLE`	503	Retry.
`GATEWAY_TIMEOUT`	504	Narrow the query with filters, then retry.

Rate limits

Each key has a request budget that refills over time. Responses carry headers that show where you stand:

Header	Meaning
`X-RateLimit-Limit`	Requests the key can make in a burst
`X-RateLimit-Remaining`	Requests left in the current budget
`X-RateLimit-Reset`	Seconds until the budget is full again

A key that spends its budget, or has too many requests in flight at once, gets 429 RATE_LIMITED with a Retry-After header. Wait that many seconds before retrying.

Contacting support

Every response, success or failure, carries requestId in the body and the same value in the X-Request-ID header. Include it when you email support@clearskies.cc so we can find the exact call.

Welcome to Clearskies

Getting Started

Unifying GTM Data

Building with Clearskies

Ask AI

Use Cases

Support

Errors and rate limits

Errors

Rate limits

Contacting support