API & MCP

Limites e headers

Os limites valem por conta e somam o REST e o MCP: as ferramentas do agente gastam os mesmos contadores da API. Ao estourar, a resposta diz quanto esperar.

Onde	Limite	Janela	Ao estourar
`POST /v1/quote` e a ferramenta `quote_solar`	60 por conta	60 segundos, deslizante	REST: `429 rate` com `Retry-After`. MCP: resultado com `isError` e `(rate)` no texto
`GET /v1/coverage`, `check_coverage`, `list_kits` e `coverage_status`	120 por conta	60 segundos	o mesmo
`GET /v1/proposals`, `GET /v1/proposals/{id}` e `get_proposal`	120 por conta	60 segundos	o mesmo
`/api/mcp`, toda mensagem JSON-RPC (o transporte)	120 por conta	60 segundos	HTTP `429`, erro `-32000` e `Retry-After`
Rotas com chave (REST e MCP), antes da autenticação	300 por endereço IP	60 segundos	REST: `429 rate`. MCP: HTTP `429`, erro `-32000`
Chave de teste	50 por dia na conta	até a meia-noite de Brasília	REST: `429 teto-teste`, sem `Retry-After`. MCP: resultado com `(teto-teste)` no texto
Propostas gravadas	50.000 por origem (a API e a página de captação contam separado)	não volta com o tempo	`429 teto-leads`, sem `Retry-After`: fale com o suporte
Corpo da requisição	4 KB no REST, 16 KB no MCP	por requisição	REST: `413 payload-grande`. MCP: erro `-32600`

"Por conta" quer dizer que a chave viva e a de teste dividem o mesmo limite por minuto. Usar o REST e o MCP juntos não multiplica nada.

A cota da chave de teste é de 50 por dia na conta, somando as requisições REST e as chamadas de ferramenta do MCP; conectar e listar as ferramentas não gasta. A cota volta à meia-noite de Brasília. No REST, conta toda requisição autenticada, inclusive a recusada. No MCP, conta cada chamada de ferramenta (tools/call), com ou sem erro; o initialize, a notificação de inicializado, o tools/list e o ping não gastam. Com a cota esgotada o agente ainda conecta e lista as ferramentas, e só a chamada volta com (teto-teste).

Cabeçalhos

As respostas trazem cabeçalhos de rastreio e de uso. Os X-RateLimit-* aparecem nas respostas das chamadas autenticadas; o 401 e o 403 de autenticação saem sem eles.

Header	Significado
`X-Request-Id`	Id único da requisição (também vem no corpo como `requestId`). Cite-o ao pedir suporte.
`X-Api-Version`	Versão da API (atualmente `1`).
`X-RateLimit-Limit`	Máximo de requisições na janela.
`X-RateLimit-Remaining`	Quantas ainda restam na janela atual.
`X-RateLimit-Reset`	Segundos até a janela reiniciar.
`X-Ionluz-Sandbox`	Presente com o valor `1` quando a chamada usou a chave de teste.
`Retry-After`	Presente nos `429` de janela (`rate`): espere estes segundos antes de repetir. O `429 teto-leads` e o `429 teto-teste` não o enviam: esses limites não voltam em segundos.

API v1 · ionluz, propostas solares honestas. Dúvidas? Cite o requestId ao escrever para suporte@ionluz.com.br.