Rate limits & retries
Alderstone calls your middleware synchronously while users are working, so latency and failure handling directly shape the user experience. This page describes what Alderstone does on its side and what your middleware should do on yours.
What Alderstone does
- Every REST call has a 30-second timeout. A slow response is treated the same as a failure.
- Connection tests may retry transient 5xx and network errors once. PO workflow calls do not retry; errors surface to the operator immediately, so returning a fast, clear error response.
- Native connector calls are throttled by a sliding-window rate limiter on Alderstone's side; REST calls are paced by user actions and sync jobs.
What your middleware should do
| Concern | Guidance |
|---|---|
| Latency | Target under 2s p95 for catalogue search and under 5s for sale-draft. Operators are waiting on these calls in the UI. |
| Idempotency | sale-draft and the push endpoints must tolerate duplicate requests carrying the same business key (poNumber, invoice identity); return the existing record instead of creating another. |
| Rate limits | When throttled, return 429 with a Retry-After header instead of queueing indefinitely. Alderstone surfaces these as workflow errors the user can retry. |
| Pagination | Honour limit parameters and return empty arrays (or hasMore: false) when exhausted; do not error on an out-of-range page. |
Upstream ERP limits
Your middleware sits between two rate regimes: Alderstone's calls on one side and your ERP vendor's API limits on the other. Respect the vendor limits: cache stable data (catalogue browses, address lists) where freshness allows, and shed load with 429 responses to Alderstone instead of letting ERP throttling turn into timeouts.