Errors & rate limits

Beta

REST v1 error codes, response format, and org API key rate limits.

Success response#

{
  "success": true,
  "data": { },
  "meta": {
    "timestamp": "2026-01-01T00:00:00.000Z",
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

meta pagination fields appear on list endpoints when applicable.

Error response#

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": { }
  },
  "meta": {
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}

Common error codes#

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Missing or invalid auth
`FORBIDDEN`	403	Not a member or insufficient role
`INSUFFICIENT_SCOPE`	403	Org API key missing required scope (`rest:read`, `rest:write`, `portfolio:read`)
`SUBSCRIPTION_REQUIRED`	403	Org billing incomplete for API access
`NOT_FOUND`	404	Resource or org not found
`VALIDATION_ERROR`	400	Invalid body or query
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error
`SERVICE_UNAVAILABLE`	503	Transient dependency failure

Rate limits (org API keys)#

Surface	Limit
REST v1 (org key)	200 requests / minute per key
HTTP MCP (org key)	120 requests / minute per org key

Response headers on REST:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset (ISO timestamp)

MCP usage is visible in manager Developers → Usage (7-day tool breakdown; no request payloads stored).

Tips#

Use exponential backoff on 429 and 503
Rotate keys if you suspect a leak; revoke in Developer Center immediately
Prefer server-side key storage only — never embed keys in tenant-facing apps