NutraSoft food manufacturing ERP software
Esc
  • GuideGetting startedThree steps to your first call and your first order, then the two shapes every response takes.
  • GuideAuthentication and keysBearer keys, test and live environments, rotation without an outage, and what each scope grants.
  • GuideTest modeA second NutraSoft account of your own, seeded with realistic data, that you can safely break.
  • PageErrorsEvery error code the API returns, what it means, what to do about it and whether to retry.
  • PageConventionsThe rules every operation follows: money, time, paging, sorting, nulls, PATCH and identifiers.
Menu

Rate limits and retries

300 requests per minute per account, the headers that report it, and which failures to retry.
Updated

In short

  • 300 requests per minute per account, shared by every key. Test mode has its own budget.
  • On 429, wait for Retry-After. Retry 503 with backoff; retry 500 on reads, and on writes only with an Idempotency-Key.
  • Never retry any other 4xx: it will fail the same way until you fix the request.
  • Quote the X-Request-Id of a failing request when you contact support.

The limit

  • 300 requests per minute per account, shared by every key on the account. Creating more keys does not buy more throughput.
  • Test mode has its own budget, so a test suite never slows your live integration down.
  • GET /organization reports the limit that applies to your key as rate_limit_per_min.
  • The window is fixed, not sliding: it resets at the start of each minute.
HeaderMeaning
X-RateLimit-LimitRequests allowed per minute
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetWhen the window resets, in Unix seconds

Over the limit, requests get 429 RATE_LIMITED with a Retry-After header: the number of seconds until the next window, never longer than the window itself. Repeated failed authentication from one IP address is throttled separately.

What to retry

ResponseRetry?How
429 RATE_LIMITEDYesWait for Retry-After, then retry. Safe on every operation.
503 SERVICE_UNAVAILABLEYesWe were briefly out of capacity. Wait the seconds in Retry-After, then retry with exponential backoff and jitter.
500 INTERNAL_ERRORReads, yesRetry reads with backoff. Before retrying a write, check whether it landed, or send it with Idempotency-Key where the operation accepts one.
Any other 4xxNoThe request will fail the same way. Fix it first.

A request whose database work runs longer than about 15 seconds is stopped and returns 500 INTERNAL_ERROR. If a read keeps hitting that limit, narrow its filters or ask for a smaller page.

Backoff

  • Back off exponentially, starting around one second, with random jitter so retries from several workers do not arrive together.
  • Cap the number of attempts and surface the error, with its request_id, once you give up.
  • Keep concurrency modest. Parallel workers share the account's limit and all receive 429 together.

Request ids

Every response carries an X-Request-Id header that we generate, starting with req_, and every error repeats it in the body as request_id. Quote it in any support request. If you send your own X-Request-Id header, we log it next to ours so you can join your logs to our records, but responses always carry the id we generated.

Paging within the limits

  • limit accepts 1 to 200 and defaults to 50. A larger value is refused with 400, not silently clamped.
  • offset accepts 0 to 10,000. Past that, use updated_since or narrower filters instead of paging deeper. See Lots and incremental sync.
  • Use has_more to decide whether to fetch the next page.