e-conomic API Limits: What They Mean for Invoice Automation at Volume
It’s the last working day of the month and 3,000 invoices are queued for booking. Halfway through the run, the integration starts returning errors. Some invoices are booked and some aren’t, and nobody can say which without checking by hand.
This is rarely an e-conomic outage. More often, the integration has hit the API’s rate limit, or it is spending its budget on calls it didn’t need to make. If your finance processes depend on an e-conomic API integration, both problems surface on your busiest days.
How e-conomic API Limits Work Today
The token bucket model
e-conomic limits API traffic with a token bucket. Each application gets its own bucket for each e-conomic agreement it connects to, identified by the app’s secret token and the agreement’s grant token. The bucket has a burst capacity and refills at a fixed rate. e-conomic gives 2,000 tokens and 30 tokens per second as examples, not as guaranteed values for your agreement.
Every request takes tokens from the bucket. When the bucket is empty, further requests are rejected with HTTP 429 until it refills.
Not every call costs the same
Each endpoint has a call cost that reflects the load it puts on e-conomic. Reading an account costs about 1 token, GET /self about 5, and reading a booked invoice about 13. An integration that makes many expensive reads uses up its budget much faster than its request count suggests.
What the response headers tell you
Every response tells the integration where it stands. X-RateLimiting shows remaining tokens against the total. X-CallCost shows what the last request cost. On a 429, Retry-After says how many seconds to wait.
Older fair-use limits
Some third-party documentation still cites a daily call cap per agreement.
What Happens When an Integration Hits the Limit
Not every error should be retried
A 429 is temporary. The bucket refills and requests usually go through again within seconds. Other status codes need different handling:
400 Bad Request: the data failed validation. e-conomic returns annotated errors that point to the failing field, and for multi-line invoices, the failing line. Retrying the same payload only spends tokens again.
401 Unauthorized: the credentials are wrong, or the agreement has revoked the app’s grant. This needs a person, not a retry.
500 Internal Server Error: something went wrong on e-conomic’s side. A delayed retry is reasonable.
An integration that retries everything blindly turns one bad invoice into a drained bucket for every other invoice in the batch.
The business impact
For finance teams, a mishandled limit shows up as:
invoices not booked before period close
duplicate postings after retries
inbound supplier invoices waiting in a queue nobody is watching
reconciliation gaps that surface weeks later in the momsangivelse preparation
Where Invoice Automation Breaks at Volume
Month-end and batch peaks
Take e-conomic’s example figures. Reading back 3,000 booked invoices one at a time, at about 13 tokens each, costs around 39,000 tokens. The first 2,000 go out in a burst. The remaining 37,000 take roughly 20 minutes at 30 tokens per second.
One app carrying every flow
The bucket is per application and agreement. One integration that handles outbound customer invoices, inbound supplier invoices and payment reconciliation draws on a single budget. A peak in one flow slows the others.
Chatty integrations
An integration that looks up the customer, product, VAT code and payment terms separately for every invoice multiplies its token spend. The lookups often cost more than the posting itself.
Designing an e-conomic API Integration That Scales
Classify errors, then back off
On a 429, wait for the time in Retry-After. If the header isn’t there, use exponential backoff: wait 1 second, then 2, then 4. Send 400 errors to a correction queue with the annotated error details, and raise 401 errors as alerts.
Use idempotency keys on every write
Send a unique Idempotency-Key header with each POST or PUT. If a response is lost in transit, retry with the same key. e-conomic returns the original result instead of creating a duplicate, flags it with X-ResultFromCache, and charges no tokens for it.
Two limits apply. Keys are cached for one hour only, and they don’t work on GET requests. Your integration must generate and store the keys itself.
Read in pages, not one by one
Collections return 20 items per page by default, and the pagesize parameter raises that to 1,000. Reading booked invoices or entries in large pages replaces thousands of single-item calls.
Filter and cache master data
Use the $in: filter to fetch up to 200 customers or products by number in one request. Then cache the results, because customers, products and VAT codes change far less often than invoices are posted.
Queue instead of bursting
e-conomic recommends sending requests one at a time rather than in parallel. A queue that throttles against X-RateLimiting keeps throughput predictable at month-end.
Where an Integration Layer Fits
HubBroker works as an integration layer on top of e-conomic, not a replacement for it. Our e-conomic integration handles outbound customer invoices and inbound supplier documents. It tracks which documents were delivered, accepted or failed.
On the API side, our ERP API integration is built around each ERP’s real API behaviour, including its rate limits. Every call and error is logged in one place, so a 429 at month-end shows up as a queued retry rather than a missing invoice.
Inbound e-invoices can arrive through our Peppol Access Point and are posted to e-conomic at a controlled pace instead of in bursts.
FAQ
What is the e-conomic API rate limit?
e-conomic uses a token bucket for each application and agreement, with a burst capacity and a fixed refill rate. The X-RateLimiting header shows your actual values.
What does HTTP 429 mean in e-conomic?
Your integration has used up its token budget. Wait for the time in Retry-After, then retry.
Should I retry a 400 error?
No. A 400 means the data failed validation. Fix the field named in the annotated error, then resend.
Do all endpoints cost the same?
No. Costs range from about 1 token for simple reads to about 13 for reading a booked invoice. X-CallCost shows the cost of each call.
Can I test against the API without an agreement?
Yes. The demo agreement allows read-only GET requests, so it is useful for exploring data structures but not for testing invoice posting.
How do I avoid duplicate invoices on retry?
Send an Idempotency-Key header with every write. e-conomic recognises a repeated key for one hour and returns the original result instead of posting again.
Running e-conomic at Volume?
If your month-end runs are slowing down or need manual clean-up, talk to our integration team about how your e-conomic API integration handles load.
