Limites de taxa
Por padrão, um token de API do Nodaro aceita 30 execuções por minuto, até 120. Veja limites por rota, os dois códigos 429, tamanhos de lote e backoff.
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 uma tarefa 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
rateLimitemPATCH /v1/api-tokens/:id. - Só duas rotas contam:
POST /v1/api/runeGET /v1/api/workflows. - As leituras não contam.
GET /v1/api/status/:execId,GET /v1/api/result/:execIdeGET /v1/api/schemanã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
| Rota | Limite | Resposta acima do limite |
|---|---|---|
POST /v1/webhooks/:token (Gatilho de webhook) | 10 requisições por minuto para cada gatilho | 429 |
| As execuções de um app publicado | O limite diário de execuções do app para cada usuário | 429 rate_limit_exceeded |
POST /v1/download-video | 4 importações de vídeo em andamento ao mesmo tempo para cada conta | 429 too_many_downloads |
POST /v1/video-overlay | 30 requisições por minuto para cada usuário | 429 rate_limit_exceeded |
POST /v1/freecut-export | 10 requisições por minuto | 429 rate_limit_exceeded |
POST /v1/characters/:id/train | 3 requisições por minuto para cada token | 429 rate_limit_exceeded |
POST /v1/oauth/register | 10 requisições por minuto para cada endereço IP | 429 rate_limit_exceeded |
POST /v1/orgs | Algumas novas organizações por hora para cada usuário | 429 rate_limit_exceeded |
POST /v1/workspaces/join | 10 tentativas por minuto para cada conta e 30 para cada endereço IP | 429 rate_limit_exceeded |
POST /v1/workflows/:id/collaborators | 20 adições por minuto para cada conta | 429 rate_limit_exceeded |
| Exportações de uso em CSV | 10 por minuto para cada usuário | 429 rate_limit_exceeded |
POST /v1/orgs/:id/invitations | 500 convites por dia para cada organização | 429 bulk_invite_cap_exceeded |
GET /v1/invitations/by-token/:token, GET /v1/shots/:id, a troca de login por SSO | Um limite para cada endereço IP | 429 rate_limit_exceeded |
Dois códigos 429 diferentes
rate_limitedvem só da cota por token das rotas/v1/api/.rate_limit_exceededvem 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árias tarefas em uma chamada.
GET /v1/jobs/statusePOST /v1/jobs/batch-statusretornam até 100 tarefas cada. Veja Tarefas. - Use backoff exponencial em um
429: espere 5 segundos, depois 10, depois 20, antes de cada nova tentativa. QuandoRetry-Afterestiver presente, espere pelo menos esse tempo. - Trate os outros erros
4xxcomo 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
| Endpoint | Limite |
|---|---|
GET /v1/jobs/status?ids=… | Até 100 IDs |
POST /v1/jobs/batch-status | Até 100 IDs |
GET /v1/jobs | limit até 100 |
GET /v1/characters | limit até 500, 100 por padrão |
GET /v1/objects, /v1/creatures, /v1/locations, /v1/faces | limit até 500 |
GET /v1/credits/transactions | limit de 1 a 50, 20 por padrão |
POST /v1/credits/model-costs | Até 50 IDs de modelo |
GET /v1/community/browse | limit até 50, 20 por padrão |
GET /v1/orgs/:id/members | limit até 200, 50 por padrão |
POST /v1/orgs/:id/invitations | Até 200 endereços em uma chamada |
| Tokens de API | 10 para cada conta |
| Apps de desenvolvedor OAuth | 5 registrados manualmente para cada usuário |
Perguntas frequentes
Qual é o limite de taxa de um token de API do Nodaro?
30 requisições por minuto por padrão, e você pode aumentar para 120 em cada token. O limite conta só as execuções e as listagens de workflows, POST /v1/api/run e GET /v1/api/workflows.
A consulta periódica (polling) conta no meu limite de taxa?
Não. Ler o status de uma execução, o resultado dela ou o schema de um workflow não usa a cota do token, e as leituras de status de tarefas também não. Consulte periodicamente a cada 2 a 5 segundos.
O que devo fazer quando recebo um erro 429?
Espere e tente de novo com backoff exponencial, por exemplo depois de 5, 10 e 20 segundos. Quando a resposta tiver um cabeçalho Retry-After, espere pelo menos esse tempo. Baseie a sua lógica de novas tentativas no status 429, não no código de erro.
Como consigo um limite de taxa maior?
Aumente o limite de taxa do token para até 120 requisições por minuto. Para ir além disso, crie mais tokens, até 10 por conta, e distribua as suas requisições entre eles.
Os gatilhos de webhook têm limite de taxa?
Sim, separado do limite dos tokens de API. Cada Gatilho de webhook aceita 10 requisições por minuto na própria URL.
Páginas relacionadas
Autenticação
Erros
Tarefas
Webhooks
Workflows
Última atualização
Erros
Todo erro da API do Nodaro tem status HTTP e código estável em um envelope. Veja o que cada código significa, quais repetir e como tarefas relatam falhas.
Especificação OpenAPI
Baixe a especificação OpenAPI 3.1 do Nodaro em /v1/openapi.json, veja os endpoints que ela cobre e gere clientes tipados em Go, Rust, Python e mais.