Rate limits and pagination in the Fortnox API

Fortnox counts requests in a rolling five-second window rather than resetting the quota at fixed times. A traffic burst can therefore keep producing 429 responses until enough older calls have left the window. Fortnox also states the limit as 300 calls per minute per client ID and tenant. In practice, schedule against the stricter short window: no more than 25 request starts during any rolling five-second period.

The quota follows the access token, not the IP address. Each Fortnox company has its own token and quota, while concurrent processes for one company share the same allowance. Coordinate throttling centrally per company and token, and reserve some capacity for interactive requests.

HTTP 429 is a signal to slow down, not to resend immediately. Put retries in a shared client and use exponential backoff with jitter so concurrent workers do not wake together and create another spike. Cap both the delay and number of attempts, then return exhausted work to a controlled queue.

Production integrations need retry and circuit breaking. Our production client uses three retries with exponential backoff from 1 to 30 seconds, a circuit breaker that opens after five consecutive failures, and a queue capped at 100 waiting calls. The circuit protects an unhealthy dependency while the bounded queue provides backpressure.

1. Throttle per access token before sending and share the limiter across every job for that tenant.
2. On 429, wait with exponential backoff and random jitter; never retry in a tight loop.
3. Open the circuit after repeated failures, measure queue depth, and alert before backlog affects customers.

Fortnox list resources use page for the page number and limit for the record count. The default limit is 100 and the supported range is 1–500. A real invoice request can fetch the first 100 unpaid invoices sorted by document number. Use lowercase query names and combine them with &. A moderate page size can be cheaper to retry and process than always requesting 500 records.

GET https://api.fortnox.se/3/invoices?filter=unpaid&page=1&limit=100&sortby=documentnumber&sortorder=ascending

Many classic Fortnox list responses contain MetaInformation with @CurrentPage, @TotalPages, and @TotalResources. Read these values where the response exposes them and continue while CurrentPage is less than TotalPages. Persist results before advancing the checkpoint so an interruption cannot skip a page.

The bundled OpenAPI document confirms /3/invoices and its resource-specific query parameters, while global page, limit, and sortorder are documented in Fortnox's official parameter guide rather than directly on that operation. Response models vary, so inspect the contract for each resource instead of requiring MetaInformation everywhere.

For invoices, ?filter=unpaid is the documented way to retrieve unpaid records only. The bundled OpenAPI document also allows cancelled, fullypaid, unpaidoverdue, and unbooked. Server-side filtering means smaller responses, fewer pages, and less quota consumption than discarding records locally.

Use sortby and sortorder for ordering. For /3/invoices, the OpenAPI document allows fields including documentnumber, customername, customernumber, invoicedate, ocr, and total; Fortnox's official example uses sortorder=ascending. Choose stable ordering for pagination and make long-running syncs able to overlap and deduplicate records changed during the run.

The global lastmodified parameter retrieves records changed since a timestamp and is the basis of incremental sync. Fortnox allows it alongside one resource-specific search parameter. Store the last successful watermark per company and resource, overlap the next interval slightly, and apply idempotent updates to catch late changes without duplicates.

A robust incremental sync starts from a stored lastmodified checkpoint, reads every page in a deterministic order, and advances the checkpoint only after the interval completes. On failure, resume from the previous safe point. Add a time overlap and upsert by Fortnox identity so network failures and boundary-time updates are harmless.

Batch reads with list pages instead of one detail call per record, but keep concurrency low per token. Let a scheduler balance background syncs against user-driven traffic and spread scheduled jobs over time. Measure request counts, 429s, retries, latency, and queue depth per company.

Cache data that is read often and changes rarely. Cache immutable lookups and short-lived list results, invalidate after your own changes, and use lastmodified to refresh only changed data. Caching reduces duplicate calls and preserves quota for workflows that need current data.