# 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.

Source: https://nodaro.ai/pt-BR/docs/developers/api/rate-limits

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:

```json
{ "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](https://nodaro.ai/docs/developers/api/authentication).

## Outros limites
| Rota | Limite | Resposta acima do limite |
| --- | --- | --- |
| `POST /v1/webhooks/:token` ([**Gatilho de webhook** (Webhook Trigger)](https://nodaro.ai/docs/nodes/automate/webhook-trigger)) | 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_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](https://nodaro.ai/docs/developers/api/jobs#poll-many-jobs-at-once).
- **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](https://nodaro.ai/docs/developers/api/errors).

```ts

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 |

## Frequently asked questions

### 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 jobs 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.