Limites de Taxa

O VDClip aplica limite de taxa à API para que uma integração não esgote a capacidade compartilhada. Quando você envia requisições mais rápido do que seu plano permite, a API responde com 429 Too Many Requests e um cabeçalho Retry-After dizendo quanto esperar.

Isso se aplica à superfície REST em https://api.vdclip.com/v1/* (autenticada com Authorization Bearer). Os endpoints OAuth 2.1 sob /oauth2/* e /.well-known/* têm limite de taxa separado.

Como é uma resposta com limite atingido

Quando você excede seu limite, os endpoints /v1 retornam HTTP 429 com o resposta JSON direta padrão. O errors[].code é RATE_LIMITED, e um cabeçalho Retry-After carrega os segundos a esperar.

HTTP/1.1 429 Too Many Requests
content-type: application/json
retry-after: 12
 
{
  "errors": [
    {
      "code": "RATE_LIMITED",
      "description": "Rate limit exceeded. Retry after 12 seconds."
    }
  ]
}

Quando Retry-After está presente, aguarde pelo menos esse tempo antes de repetir. Um loop de retry apertado não vai te desbloquear mais cedo e pode estender o tempo de espera.

Lidando com o 429 no código

Respeite o Retry-After quando presente, caso contrário recorra a backoff exponencial com jitter. Repita apenas em respostas 429 e 5xx, e desista após um número limitado de tentativas.

const BASE_DELAY_MS = 1000
const MAX_DELAY_MS = 30_000
const MAX_ATTEMPTS = 5
 
async function callVdclip(path: string, init: RequestInit = {}) {
  let attempt = 0
  let delay = BASE_DELAY_MS
 
  while (true) {
    const res = await fetch(`https://api.vdclip.com${path}`, {
      ...init,
      headers: {
        'Authorization': process.env.VDCLIP_API_KEY!, // server-side only, never in the browser
        'Content-Type': 'application/json',
        ...init.headers,
      },
    })
 
    // Success, or a non-retryable error: return and let the caller handle it.
    const isRetryable = res.status === 429 || res.status >= 500
    if (!isRetryable || attempt >= MAX_ATTEMPTS - 1) return res
 
    // Prefer the server's Retry-After. Otherwise back off exponentially with jitter.
    const retryAfter = Number(res.headers.get('retry-after')) * 1000
    const jitter = Math.random() * delay * 0.4
    const wait = retryAfter > 0 ? retryAfter : delay + jitter
 
    await new Promise((resolve) => setTimeout(resolve, wait))
    delay = Math.min(delay * 2, MAX_DELAY_MS)
    attempt++
  }
}

A mesma lógica funciona em qualquer linguagem. Duas regras importam: confie no Retry-After primeiro, e adicione aleatoriedade ao seu delay de fallback para que muitos clientes não repitam todos no mesmo instante.

Quais erros repetir

Nem toda falha deve ser repetida. Repetir uma requisição que falhou por um motivo do lado do cliente desperdiça tentativas e pode acionar a proteção contra abuso.

Para a lista completa de códigos de erro e seus formatos, veja Erros.

Endpoints OAuth 2.1

O Servidor de Autorização OAuth 2.1 em /oauth2/* e /.well-known/* tem limite de taxa independente da superfície de chave de API e usa corpos RFC padrão. Se você construir um cliente MCP, de agente ou de integração que autentica com Authorization: Bearer <JWT>, aplique a mesma disciplina: respeite o Retry-After, faça backoff no 429 e armazene em cache os documentos de descoberta e o JWKS em vez de buscá-los a cada chamada.

Reduzindo a frequência com que você atinge o limite

Alguns hábitos mantêm você confortavelmente abaixo da sua vazão.

• Pagine em vez de fazer polling agressivo. Os endpoints de listagem usam paginação por cursor (cursor e limit). Percorra os resultados com o cursor retornado em vez de re-requisitar a primeira página em um loop.
• Faça polling de trabalhos longos com calma. Renders e outros jobs assíncronos terminam no próprio ritmo. Faça polling de status em um intervalo com backoff em vez de em um loop apertado.
• Agrupe quando puder. Junte trabalho relacionado em menos requisições quando um endpoint suportar.
• Faça cache de dados estáveis. Templates, assets do brand kit e detalhes da conta mudam raramente. Faça cache deles do seu lado em vez de re-buscar a cada operação.

Dicas e Boas Práticas

Perguntas Frequentes