NUACOM API

Getting started

Rate limits

The API counts requests in fixed one-minute windows and refuses the ones above the allowance with 429. Every response tells you where you stand, so a well-behaved client never has to guess.

The allowance

  • 3000 requests per minute, counted per calling IP address: every request from the same address shares the allowance, whichever API key or session token it carries. The window is fixed, not sliding: it opens with the first request and resets a minute later.
  • A per-account allowance can be applied on top by NUACOM. It defaults to 3000 requests per minute and is counted for the account as a whole: every token of the account and every API version draw on the same budget, and refused requests count too. NUACOM support can raise, lower or lift it for an account; contact support if your integration needs more.
  • A few operations have a guard of their own. POST /v2/sms/send answers 429 with {"code": null, "error": "Too many SMS requests. Please try again shortly."} when a send cannot start because the previous one is still being processed; wait a moment and resend.

What the API tells you

Every response carries two headers:

Header Meaning
X-RateLimit-Limit The allowance for the window
X-RateLimit-Remaining Requests left in the current window

When both allowances apply, the headers report the one with fewer requests left.

Once the allowance is used up the API answers 429 and the request is not executed:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1777640400

{"message": "Too Many Attempts."}

Retry-After is the number of seconds until the window resets; X-RateLimit-Reset is the same moment as a Unix timestamp.

Staying under it

  1. Honour the headers. Slow down when X-RateLimit-Remaining gets low. On 429, sleep for Retry-After seconds and resend the same request; if it repeats, back off exponentially with some jitter. Never retry in a tight loop.
  2. Be told, not poll. Register a webhook with POST /v2/webhook-subscriptions for inbound and outbound messages and the other events the Webhooks guide lists, instead of polling the call log or the inbox.
  3. Use the bulk forms. One request instead of many: callIDs[] on GET /v2/call-notes, to[] on POST /v2/sms/send, POST /v3/groups/contacts/bulk, DELETE /v3/contacts with contacts[], and POST /v3/contacts/import for a whole file.
  4. Page big, cache small. perPage goes up to 500 on GET /v3/contacts and per_page has no cap on GET /v2/call-log. Reference data such as the extension list or the tag catalogue changes rarely: fetch it once and cache it.
  5. Narrow by date. Ask the call log for the window you need with from_date and to_date instead of re-reading history.