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

Errors raised by the API carry a consistent 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

Error codes

Branch on errorCode rather than parsing message - messages may be reworded, codes are contract. The ones you’re most likely to handle:

`errorCode`	Status	Meaning
`VALIDATION_ERROR`	400	Request failed validation - see `details[]` for the offending fields
`MALFORMED_BODY`	400	Body missing or unparseable
`WRONG_APPLICATION`	400	The connection you passed belongs to a different application than the tool
`NOT_FOUND`	404	The connection, tool, or toolset doesn’t exist (or isn’t yours)
`NO_DEFAULT_CONNECTION`	409	No default connection for the tool’s application - pass `?connectionId=` or set a default
`NO_TOOLSET_CONNECTION`	409	The toolset has no connection for the tool’s application
`TOOL_NOT_IN_TOOLSET`	403	The tool isn’t in the toolset’s allow-list
`CONNECTION_NOT_IN_TOOLSET`	403	The connection isn’t part of the toolset you scoped to
`ACCOUNT_USER_INACTIVE`	403	The acting user is no longer active on the account

New codes may be added over time - treat an unrecognized errorCode as a generic failure of its HTTP status rather than erroring out.

Rejections that happen before your request reaches the API - an invalid or missing credential (401) and unmatched routes (404) - currently return an empty body. Don’t parse the body to detect auth failure; branch on the status code, and use the x-request-id response header (returned on every request) when contacting support.

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

Resources

Error envelope

Error codes

Rate limits

​Pagination

​Error envelope

​Error codes

​Rate limits

Pagination

Error envelope

Error codes

Rate limits