Integrating with marketplace APIs: rate limits, errors and why stock figures diverge

Short answer: stock figures on marketplaces diverge not because the integration is badly written, but because it was written as an ordinary REST client. Platform APIs behave differently: limits differ per method, some operations run asynchronously, data is corrected retroactively, and half the errors are transient and need a retry rather than a log line.

Here is what breaks and what scaffolding it needs.

Limits: not one for the whole API

The first surprise on moving from tutorial examples to real work is that the rate limit is set per method rather than for the API as a whole, and the values differ by multiples.

The practical consequence: reasoning like “we make a hundred requests a minute, the limit is a thousand, we are fine” is useless. You can hit the wall on one specific method while staying comfortably inside the overall budget. Accounting has to be per method.

The second consequence is bulk operations. Updating prices on two thousand items, implemented naively, becomes two thousand consecutive requests, some of which are rejected. Rejected requests mean some items keep the old price — and there is a divergence created by the synchronisation system itself.

A buffer with priorities

The fix is well known: accumulate changes and send them in batches within the limit. But there is a nuance that separates a working implementation from a textbook one.

Not all changes are equal. A price change of one unit can wait five minutes. An item dropping to zero stock cannot: in those five minutes somebody orders what does not exist, and the platform issues a cancellation penalty.

So the stream is split into at least two lanes: a priority lane for critical events and an ordinary one for everything else. The test is simple — what happens if this change arrives five minutes later.

Asynchronous operations

Some platform methods do not return a result immediately: the request creates a task, and the result is collected by a separate call using an identifier.

That changes the logic of the integration. A 200 OK on creating the task does not mean the data was accepted, it means the task was queued. It can fail a minute later, and only whoever comes back for the status will find out.

Integrations written without accounting for this show successful sends in the logs while the changes were never applied. That is the nastiest class of divergence: the system is confident everything is fine.

Errors: transient versus permanent

Handling errors by logging and moving on leads to silent data loss. Errors have to be distinguished.

Transient — rate limit exceeded, timeout, a 500 from the platform, service unavailable. The correct response is a retry with a growing pause. On marketplaces these errors are not the exception but the norm: platforms degrade under load regularly, especially during sales events.

Permanent — item not found, malformed format, no permission, invalid value. Retrying is pointless: however many times you send it, the result will not change. These go to a separate queue for a human to review.

Mixing the two is the classic mistake. Endless retries of a permanent error eat the rate limit and block normal requests, while the absence of retries on a transient one means a lost change.

Idempotency

Retries raise a question: will sending it again create a duplicate?

For stock updates this is usually safe — the operation is idempotent by nature, and setting the same value again changes nothing. For creating entities and for document operations it is not. There you need an idempotency key or a check before creating.

A practical rule: before adding an automatic retry, answer what happens on a double execution. If the answer is “not sure”, it is too early for the retry.

Data corrected retroactively

A separate feature of these platforms: reports for past periods get recalculated. Commission is refined, a return is processed two weeks later, logistics is corrected.

An integration that fetched the report once and stored the total will be relying on stale figures. The working approach is to keep the raw responses and recompute the views rather than storing only the result. Then a change in history is handled by recomputation instead of manual reconciliation.

More on that in marketplace unit economics, where the staging layer is the central decision.

Reconciliation is mandatory

No amount of error handling gives a guarantee. A message is lost, a task fails, the platform accepts a request and does not apply it.

So a full daily reconciliation is needed: compare stock and prices between the accounting system and each platform, and produce a list of discrepancies. That is both a safeguard and a quality metric — the number of discrepancies per day shows degradation before it becomes visible in money.

What monitoring must contain

The minimum without which an integration cannot be called finished:

• the delay from a change in the accounting system to it being applied on the platform;
• the share of requests rejected on rate limit — if it grows, the buffer is misconfigured;
• the size of the permanent-error review queue;
• the number of discrepancies in the last reconciliation;
• alerts to the team’s channel when a queue stalls and when errors spike.

The key criterion is the same as for any integration: the team should learn about a failure from monitoring, not from a customer or a platform manager.

In short

Marketplace APIs need scaffolding that an ordinary REST client does not: per-method limit accounting, a buffer with priorities, a distinction between transient and permanent errors, an understanding of asynchronous operations, idempotency before retries, and daily reconciliation.

Every one of these is more expensive to add later than to design in, and it is their absence rather than code quality that explains most of the stories about stock figures drifting apart again.

If this is close to your problem, look at the marketplace aggregator service and the case of one dashboard for five platforms. How this meets the accounting system is covered in accounting integration with a website and marketplaces.