Rate limits

Rate limits protect the Nodaro API from bursts of requests. Each personal API token has its own per-minute budget for workflow runs, a few routes have limits of their own, and a request over a limit answers 429 Too Many Requests. Polling a job or a run never counts against a token's budget, so you can poll every few seconds without running out.

The per-token limit

Every personal API token has a budget of requests per minute:

• 30 requests per minute by default. You set the limit when you create the token, in Rate Limit (requests/min), from 1 to 120. Change it later with rateLimit on PATCH /v1/api-tokens/:id.
• Only two routes count: POST /v1/api/run and GET /v1/api/workflows.
• Reads do not count. GET /v1/api/status/:execId, GET /v1/api/result/:execId and GET /v1/api/schema do not use the budget.
• The budget resets every minute.

A request over the budget answers:

{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }

To go faster, raise the token's limit to 120. Beyond that, create more tokens, up to 10 per account, and spread your requests across them. See Authentication.

Other limits

Two different 429 codes

• rate_limited comes only from the per-token budget of the /v1/api/ routes.
• rate_limit_exceeded comes from every other limit: the limits for each IP address on a few routes that need no token, the limits for each caller on specific routes, and a published app's daily runs.

Routes with a limit for each caller send a Retry-After header. On a route that spends credits, the server answers 503 rate_limit_unavailable when it cannot check the limit.

Base your retry logic on the 429 status. Use the code only to tell the per-token budget from the other limits.

Handle limits well

• Poll every 2 to 5 seconds. A run changes state in seconds, and faster polling gains nothing.
• Poll many jobs in one call. GET /v1/jobs/status and POST /v1/jobs/batch-status return up to 100 jobs each. See Jobs.
• Back off exponentially on 429: wait 5 seconds, then 10, then 20, before each retry. When Retry-After is present, wait at least that long.
• Treat other 4xx errors as final. Fix the request instead of retrying it. See Errors.

import { RateLimitedError } from '@nodaro/sdk'

async function withBackoff<T>(call: () => Promise<T>): Promise<T> {
  for (const seconds of [5, 10, 20]) {
    try {
      return await call()
    } catch (err) {
      if (!(err instanceof RateLimitedError)) throw err
      await new Promise((r) => setTimeout(r, seconds * 1_000))
    }
  }
  return call()
}

const { executionId } = await withBackoff(() => client.workflows.run(workflowId))

Batch and page sizes