Rate Limiting & Pagination

Rate limiting

Nexus API endpoints are subject to rate limits to protect system stability.

Tier	Limit	Scope
Standard	100 requests/minute	Per user per organization
Agent auth exchange	10 requests/minute	Per source IP
Webhook receivers	500 requests/minute	Per source IP
Bulk operations	20 requests/minute	Per user per organization

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{"error": "rate_limit_exceeded", "message": "Too many requests. Retry after 30 seconds."}

Pagination

PostgREST (database) endpoints

PostgREST endpoints use range-based pagination with the Range header:

curl https://<project-ref>.supabase.co/rest/v1/customers \
  -H "Authorization: Bearer <token>" \
  -H "apikey: <anon-key>" \
  -H "Range: 0-24"

The response includes a Content-Range header:

Content-Range: 0-24/1523

Alternatively, use query parameters:

?offset=0&limit=25

Default page size is 25 items. Maximum page size is 100 items.

Edge Function endpoints

Edge Functions that return lists use a consistent JSON envelope:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1523,
    "total_pages": 61
  }
}

Use ?page=2&per_page=25 query parameters to navigate pages.

Ordering

PostgREST supports ordering via the order query parameter:

?order=created_at.desc

Multiple columns:

?order=status.asc,created_at.desc

Filtering

PostgREST supports rich filtering:

Operator	Meaning	Example
eq	Equals	?status=eq.active
neq	Not equals	?status=neq.deleted
gt	Greater than	?total_amount=gt.100
gte	Greater or equal	?created_at=gte.2025-01-01
lt	Less than	?total_amount=lt.1000
like	Pattern match	?name=like.*acme*
in	In list	?status=in.(active,pending)
is	Is null/true/false	?deleted_at=is.null

Error format

All API errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description of the error.",
  "details": {}
}

Common HTTP status codes:

Code	Meaning
200	Success
201	Created
400	Bad request (validation error)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Not found
409	Conflict (duplicate)
429	Rate limited
500	Internal server error

AI agent notes

• agent-auth is the most tightly restricted endpoint and is limited to 10 attempts per minute per IP.
• The MCP endpoint itself uses normal bearer-token authorization. Clients should refresh the agent JWT by calling agent-auth again after expiry instead of retrying failed calls with an expired token.
• The hosted MCP server currently uses Streamable HTTP in JSON response mode, so clients should treat it as request/response MCP over HTTP rather than legacy SSE.