Limites de uso

Camada	Taxa	Burst
Chave inválida por IP	20/min	20
Empresa	200/min	40
Chave	100/min (50% da empresa)	20
Executar relatório	10/min	2
Impressão/PDF	10/min	2
Upload de anexo	30/min	5
Concorrência por empresa	5 em andamento	—

O limite de chave inválida por IP só é consumido por requisições recusadas na autenticação: 401 (chave ausente, inválida, revogada, expirada ou inativa) e os 403 account_inactive e public_api_disabled. Uma chave aceita nunca é bloqueada pelas falhas de outros clientes no mesmo IP. Esgotado, a tentativa recusada seguinte recebe 429 com layer=ip no lugar do 401 ou do 403.

Toda resposta de uma requisição com chave válida traz os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, referentes ao balde mais restritivo consumido (ou consultado) nessa requisição. O 401 e os 403 account_inactive (empresa inativa) e public_api_disabled (API pública não habilitada para a empresa) não os trazem, porque ainda não há balde de empresa ou chave a informar; o 429 com layer=ip traz os do balde de IP. Ao atingir o limite, a resposta é 429 com Retry-After (segundos até a próxima ficha) e o corpo indica a camada responsável no campo layer (ip, company, key, operation ou concurrency; quando layer=operation, o campo operation informa qual operação pesada — report, pdf ou upload).

O que fazer em cada camada

O campo layer do 429 diz qual limite foi atingido, e a resposta certa muda conforme ele:

layer	O que significa	O que fazer
ip	Muitas tentativas recusadas na autenticação a partir do mesmo IP: chave inválida (401), ou empresa inativa ou sem API pública (403 account_inactive e public_api_disabled).	Corrija a chave, ou pare de chamar até a empresa ser reativada ou habilitada: esse limite só é consumido por essas recusas.
company	A empresa toda, somando todas as chaves, atingiu o limite.	Outra chave da mesma empresa não ajuda. Reduza a taxa do conjunto de integrações e espere o Retry-After.
key	Esta chave atingiu a parte dela do limite da empresa.	Reduza a taxa desta chave. Distribuir a carga entre chaves só ajuda enquanto o limite da empresa tiver folga.
operation	O balde de uma operação pesada acabou. O campo operation traz report, pdf ou upload.	Espace só essa operação; as demais continuam disponíveis.
concurrency	Há requisições demais em andamento ao mesmo tempo.	Reduza o paralelismo, não a taxa: espere respostas terminarem antes de enviar outras.

Uma operação pesada consome o balde dela e os da empresa e da chave. Repetir uma requisição com Idempotency-Key também consome o limite.

Erro 429 rate_limited

{
  "code": "rate_limited",
  "detail": "O limite de uso da API foi atingido. Aguarde o tempo indicado em Retry-After e tente novamente.",
  "layer": "key",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 429,
  "title": "Limite de requisições atingido",
  "type": "https://developers.mspdesk.com.br/erros/#rate_limited"
}

Repetir com backoff

1. Ao receber 429, leia Retry-After (segundos) e não envie nada nesse intervalo.
2. Repita a requisição. Se receber 429 de novo, espere o novo Retry-After.
3. Se a resposta não trouxer Retry-After, use espera exponencial (1 s, 2 s, 4 s, …) com um pouco de variação aleatória, e limite o número de tentativas.
4. Em POST, repita com a mesma Idempotency-Key. Veja Idempotência.

Os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset permitem desacelerar antes de chegar ao 429.

Em situações de degradação interna do MSP Desk, o limite efetivo pode ficar abaixo do que a tabela mostra. Por isso, sempre obedeça o Retry-After, mesmo que o seu consumo pareça dentro da tabela.