Pagination, errors & rate limits

Pagination

List endpoints take two query parameters and return a consistent envelope:

Param	Meaning	Default
`offset`	Zero-based index of the first item to return	`0`
`top`	Maximum number of items to return	`100` (connections list: `25`)

{
  "items": [ ... ],
  "totalCount": 137,
  "offset": 0,
  "top": 100
}

All four fields are always present. Page until offset + items.length >= totalCount. Both SDKs auto-paginate internally - their list-style methods return the complete array.

Error envelope

Every non-200 response carries the same JSON body:

{
  "errorCode": "VALIDATION_ERROR",
  "message": "Human-readable error message.",
  "requestId": "0HN0...",
  "timestamp": "2026-08-12T10:00:00Z",
  "path": "/v1/tools/monday_create_item/execute",
  "details": [
    { "field": "fields.name", "issue": "Required field is missing." }
  ]
}

details appears only on field-level validation failures (400, errorCode: "VALIDATION_ERROR").

Status	Meaning
400	Bad request - malformed body or invalid parameters
401	Unauthorized - missing or invalid credentials
403	Forbidden - the caller lacks access to the resource
404	Not found - the resource does not exist
409	Conflict - e.g. no default connection configured for the tool’s application
429	Too many requests - rate limit exceeded
500	Internal server error - include `requestId` when reporting

POST /v1/tools/{toolSlug}/execute is special: tool-runtime failures (the downstream API errored) return 200 with isSuccess: false and an errorMessage - not the error envelope. Branch on isSuccess, not just the HTTP status.

Rate limits

Limits are enforced per account with two budgets that must both pass: a per-second burst and a sustained hourly window. Search-backed discovery calls (GET /v1/tools or GET /v1/applications with a non-empty ?search=) have their own, stricter budget because they trigger semantic search. On 429, honor the Retry-After response header (seconds): 1 when the burst window tripped, 3600 when the hourly window tripped. Back off and retry - don’t hammer.

Getting Started

Concepts

Error envelope

Rate limits

​Pagination

​Error envelope

​Rate limits

Pagination

Error envelope

Rate limits