Limites de requisições

Visão geral

A KivoSign aplica limites de requisições em todos os endpoints da API para garantir a estabilidade do serviço.

Limites HTTP

O limite vale para:

/api/v1/*
/api/v2/*
/api/v2-beta/*

Limite: 1000 requisições por minuto por endereço IP
Resposta: 429 Too Many Requests

Este é o teto global por IP. Sua organização pode ter limites próprios abaixo desse valor; nesse caso, você pode ser limitado antes de chegar ao limite global.

Resposta 429 do limite global por IP

{
  "error": "Too many requests, please try again later."
}

As respostas de /api/v1/*, /api/v2/* e /api/v2-beta/* trazem estes cabeçalhos. A única exceção são as requisições CORS de preflight (OPTIONS), respondidas antes do limitador e sem cabeçalhos de limite:

Cabeçalho	Descrição
`X-RateLimit-Limit`	Máximo de requisições permitidas na janela global atual
`X-RateLimit-Remaining`	Requisições restantes na janela global atual
`X-RateLimit-Reset`	Fim da janela global atual, como timestamp Unix em segundos

Uma resposta 429 de um limitador por janela também traz Retry-After, em segundos, com valor mínimo 1. O limite global usa janelas fixas de um minuto alinhadas ao relógio, então a espera real até a próxima janela fica entre 1 e 60 segundos. Respeite o Retry-After exatamente, em vez de esperar 60 segundos fixos. Veja o exemplo de tratamento do Retry-After.

Limites de uso

Além dos limites HTTP, sua conta tem limites de uso definidos pelo seu plano (por exemplo, documentos por mês). Consulte os limites do seu plano em Configurações da organização → Cobrança.

Respostas 429 por limite da organização

Os limites por janela e as cotas mensais da organização geram respostas 429 cujo corpo depende da versão da API, e nenhum deles é igual ao corpo { "error": "..." } do limite global por IP.

Em /api/v1/*, o corpo traz apenas uma mensagem:

{
  "message": "Too many requests, please try again later. Contact support if you require higher limits."
}

Em /api/v2/* e /api/v2-beta/*, o corpo é um objeto de erro estruturado:

{
  "message": "Too many requests, please try again later. Contact support if you require higher limits.",
  "code": "TOO_MANY_REQUESTS",
  "data": {
    "code": "TOO_MANY_REQUESTS",
    "httpStatus": 429,
    "appError": {
      "code": "TOO_MANY_REQUESTS",
      "message": "Too many requests, please try again later. Contact support if you require higher limits."
    }
  }
}

As respostas de limite por janela da organização trazem os cabeçalhos X-RateLimit-* e Retry-After da própria janela. As respostas de cota mensal não trazem cabeçalhos de limite nem Retry-After, porque a cota não é uma janela de tempo; use o código de status e a mensagem.

Códigos de erro

Código	Status	Descrição
`TOO_MANY_REQUESTS`	429	Limite global por IP, limite por janela da organização ou cota mensal excedida
`LIMIT_EXCEEDED`	400	Limite de uso de recurso excedido

Há três origens para respostas TOO_MANY_REQUESTS:

O limite global por IP, que retorna o corpo { "error": "..." } mostrado acima.
Os limites por janela da organização para os contadores api, document e email.
As cotas mensais da organização para os mesmos três contadores. Toda requisição autenticada consome o contador api, então qualquer endpoint pode retornar esse 429 quando a cota mensal de API acabar, não só os de envelope.

Veja também

Autenticação - Guia de autenticação da API
Versionamento da API - Gestão de versões da API
Primeira chamada à API - Primeiros passos com a API