Limits, errors and polling

Rate limit

• 60 requests per minute per API key, on REST and MCP alike. The window slides.
• Before a key is read, each IP address is limited to 10 requests per 10 seconds. A flood without a valid key hits this first.
• Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Reset is a timestamp in milliseconds since the epoch.
• A blocked request answers HTTP 429. It usually carries Retry-After in whole seconds. Do not rely on that header being present.

{ "error": "rate_limit_exceeded" }

The 429 body from the rate limiter is this short form. The MCP endpoint answers in JSON-RPC form with the same 429 status. A rate_limited error from a platform uses the normal envelope below.

Body size caps

Import caps

To import more than 5,000 rows as JSON, split them into several calls. The REST body cap still applies to each call.

Error envelope

Every failure from a tool answers JSON with one stable code and a readable message. A code may add extra fields, for example a reason.

{ "error": { "code": "not_found", "message": "No campaign with that id." } }

Pagination

list_reviews and inbox_list take an optional cursor and return nextCursor. Pass the returned nextCursor back as cursor for the next page. Stop when it is null or missing. customers_list takes max (1 to 100) and returns nextCursor but has no cursor input. calls_log uses since instead (next section).

No webhooks. Poll.

SwooshConnect does not send webhooks. To learn about new calls, poll calls_log. A call appears once it has ended and has been over for about five minutes, so its outcome is final. Each call arrives exactly once, oldest first.

• First poll: set since to the current time as an ISO 8601 date-time. Store it.
• Call calls_log with since set to your stored value. Use limit up to 200. The default is 50.
• Handle every call in calls.
• If nextCursor is a string, store it as the new since. If it is null, nothing new arrived. Keep your old value.
• Sleep at least a minute, then repeat from step 2. If a page was full, repeat at once.

SINCE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

curl -G -H "Authorization: Bearer $SWOOSHCONNECT_API_KEY" \
  --data-urlencode "since=$SINCE" \
  --data-urlencode "limit=200" \
  https://swooshrank.com/api/v1/connect/calls/log

let since = new Date().toISOString();

async function handle(call: unknown): Promise<void> {
  /* your logic */
}

export async function poll(): Promise<void> {
  const url = new URL("https://swooshrank.com/api/v1/connect/calls/log");
  url.searchParams.set("since", since);
  url.searchParams.set("limit", "200");
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.SWOOSHCONNECT_API_KEY}` },
  });
  if (!res.ok) throw new Error(`calls_log failed: ${res.status}`);
  const { data } = await res.json();
  for (const call of data.calls) await handle(call);
  if (data.nextCursor) since = data.nextCursor;
}

You pay for what you connect. Nothing else.