Limits

This article describes the default limits of the MplusKASSA API (SOAP) and how your client should deal with them.

In short: there is no quota per second, minute or day. The limits concern the number of concurrent (parallel) requests, timeouts, and the size of responses and uploads.

Overview

Limit Default What happens when exceeded?
Concurrent requests per API ident Unlimited (0), configurable per ident HTTP 429 Too Many Requests
Concurrent requests per API instance (all idents combined) 100 Logged only by default; if rate limiting is enabled for the instance: HTTP 429
Requests actually processed at the same time Number of worker threads of the API instance (configured per customer) Other requests wait until a worker is free
Concurrent connections via api.mpluskassa.nl 500 per API port New connections wait until there is room
syncMarkerLimit 1000 Higher values are capped at 10,000
Size of an image upload 50 MB The request is rejected with an error
TLS TLS 1.2 or higher The connection is refused

Concurrent requests

Per API ident

For each API ident you can configure how many requests it may run at the same time (setting Number of parallel requests, see API ident settings). The default is 0: no limit per ident.

If a limit is set and the ident sends more requests at once, every request above the limit immediately gets HTTP 429. The request is not executed and can safely be sent again.

Per API instance

The API instance also counts all requests that are open at that moment, across all idents. The default threshold is 100. By default, exceeding it only results in a warning in our logging (starting at half the threshold). On instances where rate limiting is enabled, requests above the threshold get HTTP 429.

Processing capacity

How many requests an API instance actually processes at the same time depends on the number of worker threads configured for that customer. Sending more parallel requests than that does not make your integration faster: the extra requests just wait. Also, all integrations of one customer share the same instance and the same database.

Timeouts

Timeout Value Meaning
Connecting (proxy → API) 5 seconds
Client-side inactivity 5 seconds Your client must keep sending the request within this time. A keep-alive connection that is idle for 5 seconds is closed.
Waiting for the API response 30 minutes Maximum time without data from the API. Very heavy requests can take long, but not indefinitely.
Socket timeout in the API itself 10 seconds For reading and writing data on the connection.

Amount of data per request

  • syncMarkerLimit: calls that use a syncMarker return at most 1000 items per call by default. With syncMarkerLimit you can change this up to 10,000; higher values are capped at 10,000. See also Sync Markers.
  • Images: an image created through the API may be at most 50 MB.

Recommendations

  1. Limit parallel requests. Preferably use one to a few concurrent requests per integration. More parallel requests usually do not make things faster.
  2. Handle HTTP 429. Wait and retry with an increasing delay (exponential backoff). The API does not send a Retry-After header.
  3. Synchronise with syncMarkers instead of fetching all data every time. Fetch large amounts of data in batches using syncMarkerLimit.
  4. Expect closed connections. If you reuse HTTP connections, make sure your client automatically opens a new connection when an idle connection was closed after 5 seconds.
  5. Use generous client timeouts for heavy calls (for example reports or large historical exports), but no longer than 30 minutes.

Do you structurally need higher limits for your integration? Contact MplusKASSA and describe which calls you make and in what volumes.

Source: MplusKASSA API: default limits