maxlag is something that can be added to anyAction API query. When set, the API query will ask the server if it is too busy.If it is, the API query will return an error instead of processing the API request.The error message will include the number of seconds behind it is, and this information can be used to determine how long to wait before retrying the query.The idea is to pause bot operations during times of high server load, to give human operations priority.This is an optional but recommended parameter, and many major bot frameworks such asPywikibot implement it by default.

If you are running MediaWiki on a replicated database cluster (like Wikimedia is), then high operation rates (especially edits) may cause the replica servers to lag.One way to mitigate replication lag is to have all bots and maintenance tasks automatically stop whenever lag goes above a certain value.In MediaWiki 1.10, themaxlag parameter was introduced which allows the same thing to be done in client-side scripts.Since 1.27, it only applies toapi.php requests.

Themaxlag parameter can be passed toapi.php through a URL parameter or POST data. It is an integer number of seconds.For example,this link shows metadata about the page "MediaWiki" unless the lag is greater than 1 second whilethis one (with-1 at the end) shows you the actual lag without metadata.

If the specified lag is exceeded at the time of the request, the API returns an error (with 200 status code, seeT33156) like the following:

{"error":{"code":"maxlag","info":"Waiting for$host:$lag seconds lagged","host":$host,"lag":$lag,"*":"See https://www.mediawiki.org/w/api.php for API usage"}}

The following HTTP headers are set:

• Retry-After – a recommended minimum number of seconds that the client should wait before retrying
• X-Database-Lag – The number of seconds of lag of the most lagged replica

Recommended usage forWikimedia wikis is as follows:

• Usemaxlag=5 (seconds). This is an appropriate non-aggressive value, set as default value onPywikibot. Higher values mean more aggressive behaviour, lower values are nicer.
• If you get a lag error, pause your script for at least 5 seconds before trying again. Be careful not to go into a busy loop.
• It's possible that with this value, you may get a low duty cycle at times of high database load. That's OK, just let it wait for off-peak. We give humans priority at times of high load because we don't want to waste their time by rejecting their edits.
• Unusually high or persistent lag should be reported to#wikimedia-tech^connect onIRC.
• Interactive tasks (where a user is waiting for the result) may omit themaxlag parameter. Noninteractive tasks should always use it. See alsoAPI:Etiquette#The maxlag parameter.

Note that the caching layer (Varnish orSquid) may also generate error messages with a 503 status code, due to timeout of an upstream server.Clients should treat these errors differently, because they may occur consistently when you try to perform a long-running expensive operation.Repeating the operation on timeout would use excessive server resources and may leave your client in an infinite loop.You can distinguish between cache-layer errors and MediaWiki lag conditions using any of the following:

• X-Database-Lag header is distinctive to replication lag errors in MediaWiki
• NoRetry-After in Varnish errors
• X-Squid-Error header should be present in Squid errors
• The response body in replication lag errors will match the regex/Waiting for [^ ]*: [0-9.-]+ seconds? lagged/

For testing purposes, you may intentionally make the software refuse a request by passing a negative value, such as in the following URL://www.mediawiki.org/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1.

• MediaWiki development