Limites de chamadas API e quotas — Portugal
Limites token-bucket, comportamento de burst e gestão de 429 para a REST API Corp-Merch em Portugal.
Arquitectura — Limites por chave e por rota em Portugal
Cada chave API tem o seu próprio token bucket por rota. Por omissão: Standard 600 req/min em /v1/orders e /v1/invoices, 1 200 req/min em endpoints read-only; Pro 10x. Bursts até 2x durante 10 segundos. Respostas com cabeçalhos X-RateLimit-Limit, -Remaining, -Reset. A emissão de facturas AT é assíncrona e não tem rate-limit no submit — apenas no polling de estado. O cálculo IVA 23% é ilimitado.
Como integrar — Respostas 429 e Retry-After
Quando excedes o limite devolvemos 429 Too Many Requests com cabeçalho Retry-After em segundos. Os nossos SDKs tratam disto com backoff exponencial e jitter; em clientes custom replica a lógica e nunca faças busy-loop. 429 sustentado > 5 minutos alerta automaticamente o nosso CS — preferimos subir o limite a ver-te falhar.
Operação e casos extremos — Quotas e fair use
Além dos rate limits, quotas mensais limitam encomendas, facturas e webhooks por tenant — dimensionadas ao contrato. Soft quotas avisam a 80% e 100% no dashboard e email; hard quotas (raras, só trial) rejeitam com 402 Payment Required. Leituras de catálogo e polling de estado Portal das Finanças (AT) são ilimitados em planos pagos.
Perguntas frequentes
Posso obter um limite mais alto?
Sim — em Pro e Enterprise ajustamos limites aos volumes contratados. Contacta o support com perfil de carga sustentado.
Os endpoints read-only são mais leves?
Sim — endpoints de leitura (GET /v1/catalog, GET /v1/orders) têm 2x o limite dos de escrita por omissão.
E os webhooks?
O throughput webhook tem budget separado — até 50/s por endpoint com backpressure; o inbound não se paga.
Gestão de burst?
O token bucket permite 2x burst por ~10 segundos, depois aplica-se o steady-state. Útil para jobs de fim de mês.
Polling AT?
O polling de /v1/invoices/{id} tem rate-limit como outras leituras; recomendamos webhooks para a notificação AT.