Errors and limits

Every Skyelight API error returns a JSON body with an error field. The field holds a sentence you can show to a person:

{ "error": "status must be 'open', 'deferred' or 'resolved'" }

Status codes

Code	Meaning	What to do
`400`	The request is invalid: a missing or invalid field, invalid JSON, or no `projectId` where one is needed.	Read `error`, fix the request and send it again. When `projectId` is missing, the message says how to list projects.
`401`	No token, a malformed `Authorization` header, or an invalid, expired or revoked token.	Check that the header is `Authorization: Bearer <token>`. Create a new token if needed.
`403`	The token is valid but can’t do this: your role doesn’t allow it, your account is in no workspace, or agent tools aren’t available (see below).	Read `error`. For plan and seat refusals, check `reason`.
`404`	The item, project or workspace doesn’t exist, or your token can’t reach it.	Check the ID. Skyelight returns `404` in both cases.
`429`	Too many requests.	Wait for the number of seconds in the `Retry-After` header, then retry.

A 401 response also has a WWW-Authenticate header. OAuth clients use it to start a new sign-in. Scripts can ignore it.

Plan and seat refusals

Agent tools, including the API, need an owner, admin or collaborator role in an organization whose plan includes agent tools. When either is missing, the API returns 403 with a body your code can check without parsing the sentence:

{
  "error": "Your seat here is reviewer, which reads and comments in the app but does not carry agent tools. An admin can change it to collaborator.",
  "kind": "billing_limit",
  "feature": "agent_tools",
  "reason": "no_seat",
  "message": "Your seat here is reviewer, which reads and comments in the app but does not carry agent tools. An admin can change it to collaborator.",
  "limit": null,
  "used": null
}

`reason`	What it means	Who fixes it
`no_seat`	You are a reviewer in that workspace.	A workspace owner or admin changes your role to collaborator or admin.
`no_plan`	The organization’s plan doesn’t include agent tools (the Free plan).	The organization owner upgrades to Pro or above. See Plans and billing.

The error sentence can change. Check kind and reason in code.

Blocked in one workspace, allowed in another

Skyelight checks access for each workspace. If your token reaches several workspaces and only some allow agent tools, requests still succeed:

GET /api/v1/workspaces lists every workspace. Blocked workspaces have available: false and the reason in unavailableReason.
A call to a blocked workspace gets the 403 above.

Skyelight refuses the whole request only when none of the workspaces your token reaches allows agent tools.

Rate limits

Each personal token can make 300 requests a minute, with bursts of up to 120. OAuth connections for one person share a single limit. Past the limit, you get a 429 with a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 4

{ "error": "Too many requests. Slow down and retry after the delay given." }

Creating threads is also subject to the per-person limits that apply in the web app. When one of those limits refuses a new thread, the API returns 400 with the reason.

Large projects

Reads that cover a whole project read its 2,000 most recent threads. When a project has more, the response includes capped: true, and counts are a minimum, not a total.

GET /api/v1/items returns at most 200 rows per call, and 50 by default. When truncated is true, narrow the filters. This endpoint doesn’t page.
GET /api/v1/review and GET /api/v1/decisions return results in pages. To read the next page, pass the previous response’s nextOffset as offset. A nextOffset of null means there are no more pages.