Rate Limiting

A API Maestron limita a taxa de requisições para garantir estabilidade e isolamento entre os consumidores. Esta página é a fonte única sobre limites, headers de controle e a resposta 429.

Granularidade

O limite é aplicado por token. Como a empresa (tenant) é resolvida automaticamente a partir do token (ver Autenticação), cada token possui sua própria janela de contagem independente. Tokens distintos — inclusive tokens emitidos para outra empresa via POST /auth/context — consomem cotas separadas.

A contagem usa uma janela fixa medida em segundos. Ao expirar a janela, o contador é zerado e o valor de X-RateLimit-Reset avança para o próximo ponto de reset.

Headers de controle

Toda resposta — bem-sucedida ou não — inclui os headers de rate limit do estado atual da janela:

Header	Tipo	Descrição
X-RateLimit-Limit	integer	Total de requisições permitidas na janela atual.
X-RateLimit-Remaining	integer	Requisições restantes na janela atual.
X-RateLimit-Reset	integer	Timestamp Unix (segundos) do momento em que o contador é zerado.

Quando o limite é estourado, a resposta 429 adiciona o header:

Header	Tipo	Descrição
Retry-After	integer	Segundos a aguardar antes de uma nova requisição.

Exemplo de headers em uma resposta dentro do limite:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1718806860

Resposta 429

Ao exceder o limite da janela, a API responde com status 429 e o envelope de erro padrão. O header Retry-After indica quantos segundos aguardar até a próxima tentativa. A descrição completa de cada código HTTP está em Erros.

GET /crm/contacts Copiar para LLM

Exemplo de estouro de limite

Qualquer endpoint autenticado retorna 429 ao exceder o limite da janela. O header Retry-After acompanha a resposta.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/v1/crm/contacts \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/crm/contacts', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/v1/crm/contacts",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/crm/contacts", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/v1/crm/contacts");
var data = await response.Content.ReadAsStringAsync();

GET /crm/contacts HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Dentro do limite401 · Não autenticado429 · Limite excedido

{
  "message": "Contatos listados.",
  "data": [],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 0,
    "last_page": 1
  }
}

{
  "message": "Token inválido ou expirado."
}

{
  "message": "Muitas requisições. Tente novamente mais tarde."
}

Nota

O header Retry-After está presente apenas na resposta 429. Os headers X-RateLimit-* acompanham todas as respostas.

Boas práticas

• Antes de cada novo lote de chamadas, verifique X-RateLimit-Remaining para evitar disparar requisições destinadas a falhar.
• Ao receber 429, respeite o valor de Retry-After antes de repetir a requisição. Aplique recuo exponencial entre tentativas sucessivas.
• Prefira endpoints de listagem com paginação a múltiplas chamadas individuais por {id}, reduzindo o número total de requisições por janela.
• Cada token tem cota independente; distribuir carga entre tokens distintos não contorna o limite agregado por empresa quando este existir.