Limites de taxa

Os limites de taxa protegem a API do Nodaro contra picos de requisições. Cada token de API pessoal tem uma cota própria por minuto para execuções de workflows, algumas rotas têm limites próprios, e uma requisição acima de um limite retorna 429 Too Many Requests. A consulta periódica de um job ou de uma execução nunca conta na cota de um token, então você pode consultar a cada poucos segundos sem esgotá-la.

O limite por token

Todo token de API pessoal tem uma cota de requisições por minuto:

• 30 requisições por minuto, por padrão. Você define o limite ao criar o token, em Limite de taxa (requisições/min), de 1 a 120. Mude depois com rateLimit em PATCH /v1/api-tokens/:id.
• Só duas rotas contam: POST /v1/api/run e GET /v1/api/workflows.
• As leituras não contam. GET /v1/api/status/:execId, GET /v1/api/result/:execId e GET /v1/api/schema não usam a cota.
• A cota é renovada a cada minuto.

Uma requisição acima da cota retorna:

{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }

Para ir mais rápido, aumente o limite do token para 120. Para ir além disso, crie mais tokens, até 10 por conta, e distribua as suas requisições entre eles. Veja Autenticação.

Outros limites

Dois códigos 429 diferentes

• rate_limited vem só da cota por token das rotas /v1/api/.
• rate_limit_exceeded vem de todos os outros limites: os limites por endereço IP em algumas rotas que não precisam de token, os limites por chamador em rotas específicas e as execuções diárias de um app publicado.

As rotas com limite por chamador enviam um cabeçalho Retry-After. Em uma rota que gasta créditos, o servidor retorna 503 rate_limit_unavailable quando não consegue verificar o limite.

Baseie a sua lógica de novas tentativas no status 429. Use o código só para distinguir a cota por token dos outros limites.

Lidar bem com os limites

• Faça a consulta periódica a cada 2 a 5 segundos. Uma execução muda de estado em segundos, e consultar com mais frequência não traz ganho nenhum.
• Consulte periodicamente vários jobs em uma chamada. GET /v1/jobs/status e POST /v1/jobs/batch-status retornam até 100 jobs cada. Veja Jobs.
• Use backoff exponencial em um 429: espere 5 segundos, depois 10, depois 20, antes de cada nova tentativa. Quando Retry-After estiver presente, espere pelo menos esse tempo.
• Trate os outros erros 4xx como definitivos. Corrija a requisição em vez de repeti-la. Veja Erros.

import { RateLimitedError } from '@nodaro/sdk'

async function withBackoff<T>(call: () => Promise<T>): Promise<T> {
  for (const seconds of [5, 10, 20]) {
    try {
      return await call()
    } catch (err) {
      if (!(err instanceof RateLimitedError)) throw err
      await new Promise((r) => setTimeout(r, seconds * 1_000))
    }
  }
  return call()
}

const { executionId } = await withBackoff(() => client.workflows.run(workflowId))

Tamanhos de lote e de página