O maxlag pode ser adicionado a qualquer consulta da Action API. Quando definido, a consulta da API perguntará ao servidor se ele está muito ocupado. 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 as Pywikibot implement it by default.

Se o MediaWiki está sendo executado em um cluster de bancos de dados replicados (como o é na Wikimedia), isso significa que um alto tráfego de operações (especialmente edições) pode causar lag nos servidores replicados. Uma forma de mitigar o lag nas réplicas é fazer com que todos os robôs e tarefas de manutenção parem automaticamente assim que o lag for superior a determinado valor. O parâmetro maxlag foi introduzido no MediaWiki 1.10, permitindo que isso seja feito em scripts executados no client-side. Desde a 1.27, ele se aplica somente a requisições à api.php.

O parâmetro maxlag pode ser passado à api.php através de um parâmetro na URL ou dos dados no POST. Seu conteúdo são os números de segundos tipados como inteiro. A título de exemplo, esta ligação retornará os metadados da página “MediaWiki” enquanto o lag for menor do que 1 segundo. Já esta outra (com um -1 no final) mostrará o lag sem os metadados.

Se o lag especificado for excedido durante a requisição, a API retornará um erro (com o código 200 conforme T33156) como o seguinte:

{
    "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"
    }
}

Os seguintes cabeçalhos HTTP são definidos:

• Retry-After - um número mínimo recomendado de segundos durante os quais o cliente deverá aguardar antes de tentar novamente
• X-Database-Lag - O número de segundos de lag na réplica com o maior lag

O uso recomendado para as wikis da Wikimedia é o seguinte:

• Use maxlag=5 (5 segundos). Esse é um valor não agressivo adequado, definido como valor padrão no Pywikibot. Valores mais altos significam comportamento mais agressivo, valores mais baixos são mais agradáveis.
• Se você receber um erro de lag, pause o script por pelo menos 5 segundos antes de tentar novamente. Tenha cuidado para não entrar em um loop contínuo.
• É possível que, com esse valor, seja obtido um ciclo de trabalho baixo em momentos de alta carga do banco de dados. Não há problema, deixe-o aguardar fora do horário de pico. Damos prioridade às ações humanas em momentos de alta carga porque não queremos desperdiçar o tempo deles rejeitando suas edições.
• Um lag anormalmente alto ou persistente deve ser relatado ao #wikimedia-tech ^connect no IRC.
• Tarefas interativas (nas quais um usuário está aguardando o resultado) podem omitir o parâmetro maxlag. As tarefas não interativas devem sempre utilizá-lo. Veja também API:Etiqueta#O parâmetro maxlag.

Observe que a camada de cache (Varnish ou Squid ) também pode gerar mensagens de erro com um código 503, devido ao tempo limite de um servidor a montante (upstream). Os clientes devem tratar esses erros de forma diferente, pois eles podem ocorrer de forma consistente ao tentar executar uma operação custosa e de longa duração. Repetir a operação no tempo limite usaria recursos excessivos do servidor e poderia deixar seu cliente em um loop infinito. É possível distinguir entre erros de camada de cache e condições de lag do MediaWiki usando um dos seguintes procedimentos:

• O cabeçalho X-Database-Lag é distinto dos erros de lag de replicação no MediaWiki
• Nenhum Retry-After nos erros do Varnish
• O cabeçalho X-Squid-Error deve estar presente nos erros do Squid
• O corpo da resposta nos erros de lag da réplica corresponderá à expressão regular /Waiting for [^ ]*: [0-9.-]+ seconds? lagged/

Para fins de teste, você pode intencionalmente fazer com que o software recuse uma requisição passando um valor negativo, como no URL a seguir: //www.mediawiki.org/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1.