Errors & limits

Response format

Successful responses wrap the result in data. Lists add meta with paging details.

{
  "data": [
    {
      "id": "6650a4c2e1b3d5f7a9c1e301",
      "name": "Acme Retail"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 2
  }
}

Errors return a non-2xx status and an error object. Branch on code; message is for people and may change. Some errors add fields, such as maxProjects or retryAfter.

{
  "error": {
    "code": "max-projects",
    "message": "Plan allows at most 3 project(s)",
    "maxProjects": 3
  }
}

Errors any request can return

These come from the key, the plan or the account, before an endpoint runs.

All error codes

Each endpoint page lists the codes it can return. A few codes depend on your role in the project: flag-… means your membership is missing that permission (see project permissions).

Rate limits

Your plan sets how many requests your account can make per rolling minute, shared across all your keys (see plans). Every response tells you where you stand:

Some actions have their own short limits, because they cost more than a read:

• Uptime probes: one per project every 30 seconds (probe-cooldown).
• Webhook test sends and redeliveries: one per endpoint every 10 seconds, 20 per minute per account.
• Requests with an invalid key are limited per IP address.

Pagination

Lists of projects, pages and findings take page (from 1) and limit (up to 100). meta.total is the number of matching items, so the last page is ceil(total / limit).

Uptime history is newest first and uses a cursor instead, because new checks arrive all the time: pass meta.nextBefore as before to get the next page, and stop when it is null. See uptime check history.

When to retry