API throttling

Mirakl marketplaces protect their APIs with rate limits. If you fire too many calls in a short time, the marketplace returns a “rate limited” response and asks you to wait. The plugin handles this in two ways: it spaces its own outgoing calls for the three big import flows, and it backs off and retries when the marketplace asks it to.

You don’t have to do anything for this to work — it’s all automatic. This page explains what happens behind the scenes so you can recognise it in the Sync Logs when a sync seems unusually slow.

What the plugin paces itself

The plugin enforces a one-minute gap between its own calls for three import flows, per marketplace:

• Product imports — the calls that upload products into the marketplace catalog.
• Offer imports — the calls that upload offers (price and stock for a given product).
• Stock imports — the calls that push stock updates only.

These three groups are independent. A pause on offer imports does not block stock imports or product imports.

Everything else — order import, message sync, document sync, invoice sync and transaction-log sync — does not use this pacing. Those flows rely solely on the marketplace’s rate-limit response (see below) to back off.

What happens during the one-minute gap

When the plugin wants to send one of the paced calls and the previous call to the same group was less than 60 seconds ago, the call is postponed by 60 seconds. The plugin doesn’t sit and wait — it puts the message back into the queue with a delay, lets the worker do other things, and picks the message up again later.

The effect you’ll see:

• In Sync Logs, a Stock sync or Product export run that would normally take a few minutes can stretch out as the plugin paces itself.
• The Processed count keeps climbing, just slower than the wall clock.
• No batch is dropped — eventual completion is guaranteed.

What happens when the marketplace says “rate limited”

If the marketplace itself responds with a rate-limit message (HTTP status 429), it tells the plugin how long to wait via the Retry-After header. The plugin obeys: it puts the message back into the queue with that exact delay, and lets the worker do other things.

The retry path is the same for every kind of sync — paced flows and non-paced flows alike. You’ll see a sync log row with the marketplace’s rate-limit text in the Message field. The next attempt picks up automatically when the delay expires.

How to tell that throttling is at work

The simplest signal is in the Sync Logs:

• A Stock sync, Product export batch or Offer sync run in Started status for noticeably longer than usual, with the Processed counter creeping up — this is the plugin pacing itself.
• A row at level Warning or Error with a message mentioning the marketplace’s rate limit — this is the marketplace pushing back. The next attempt will run automatically after the delay it returned.

If you’re seeing constant rate-limit messages on flows that aren’t paced (order import, message sync, document sync, invoice sync, transaction-log sync), the fix is to lower the corresponding interval on the Mirakl → Settings → Sync Settings tab — see Settings.

Multi-host workers

If you run several Shopware worker hosts that hit the same marketplace, by default each host paces itself independently — they don’t know about each other’s calls. For a small fleet this is usually fine, because the marketplace’s own rate-limit will catch any overshoot. For larger fleets, configure a shared lock store (Redis or Doctrine) for Symfony Lock so the hosts coordinate.

Tips and gotchas

Tip

The throttle delays calls but doesn’t drop them. A long backoff stretches a 30-minute sync into an hour, but every batch is still processed. Watch the Processed column on the Sync Logs list to see real throughput versus wall-clock time.

Caution

Don’t share one API key across two Shopware instances. Each instance paces its own calls but the marketplace counts the combined load. You’ll consistently hit rate limits because each instance thinks it’s within budget. Use one instance per seller account, or consolidate the workers behind one shared lock store.

Note

Most syncs don’t use the one-minute pacing — only product imports, offer imports and stock imports do. Order import, message sync, document sync, invoice sync and transaction-log sync rely on the marketplace’s rate-limit response alone. If you see rate-limit messages on those flows, lower the corresponding interval on the Sync Settings tab.

Related

• Sync logs — where rate-limit messages show up
• Background tasks — the scheduled tasks that send these calls
• Settings — the sync interval settings you can lower if you see rate-limit messages
• Troubleshooting — broader checklist when something is stuck