# Limites

Toda API da Inovacc limita o tamanho do que você envia, quanto tempo uma chamada pode levar e com que frequência você pode chamar. Este guia lista esses limites por API e diz o que acontece quando você atinge cada um, para que o seu código possa ficar abaixo deles ou tratar a recusa. Os valores marcados como "por organização" são definidos para a sua organização pela Inovacc; os demais são fixos.

## Como os limites respondem

| Você atinge | Resposta | O que fazer |
|---|---|---|
| Um limite de tamanho (corpo, arquivo, registro, item) | `413` (`request_too_large`, `payload_too_large`, `url_too_large`), ou `400` para um campo ou documento grande demais | Envie menos, ou use o envio em partes |
| Um limite de quantidade (documentos por chamada, operações por lote, itens por coleção) | `400 invalid_body`, `400 batch_too_large` ou `409 collection_full` | Divida a chamada; inicie uma nova coleção |
| Um limite de taxa | `429 rate_limited`, com `Retry-After` na API de IA | Aguarde e tente novamente |
| Uma cota de tokens, de custo ou de simultaneidade (IA) | `429 quota_exceeded` ou `429 concurrency_limited`, sem `Retry-After` | Diminua o ritmo por minutos, ou aumente a cota |
| Um orçamento diário (IA) | `429 budget_exhausted`, `Retry-After` até 00:00 UTC | Aguarde o próximo dia UTC |
| Um limite de entrada por requisição (IA) | `400 input_too_large` | Encurte a entrada |

Uma chamada recusada em um limite é recusada antes de o seu trabalho começar: nada é chamado em seu nome e nada é gravado.

## IA

| Limite | Valor |
|---|---|
| Corpo da requisição (chat, embeddings, run) | 1 MiB por padrão; por organização, de 1 KiB a 20 MiB |
| Tokens de entrada por requisição | por organização (`400 input_too_large`) |
| Tokens de saída por requisição | o menor entre o teto da rota e o da sua organização; um `max_tokens` maior é reduzido, não recusado |
| Tempo até o modelo começar a responder | 60 segundos (`504 timeout_error`); não em `/v1/run` |
| Imagens em uma requisição de chat | 20 |
| Custo de entrada estimado de uma imagem | 1.600 tokens |
| Resposta armazenada para uma repetição idempotente | 24 horas |
| Uma chamada mantida como em andamento | 5 minutos |
| Banco de Dados Vetorial: documentos por ingestão, ids por exclusão | 100 |
| Banco de Dados Vetorial: um documento (`id` + `text` + `metadata`) | 10 KiB |
| Banco de Dados Vetorial: corpo da requisição | 1 MiB |
| Consulta vetorial: texto; `top_k` | 8.000 caracteres; 50 |
| Item de coleção no corpo de uma requisição, ou por URL | 16 MiB |
| Coleção | 100 itens; 1 GiB de arquivos enviados em requisições; 20 GiB de vídeo por envio |
| Parte de um envio | 64 MiB, todas as partes exceto a última |
| Envio que não é vídeo (transcrição, notas) | 16 MiB |
| Envio de gravação | por organização |
| Resultado de um trabalho de conhecimento | mantido por 24 horas |
| Leituras de atividade e de uso | até 366 dias e 92 dias por chamada |

**Cotas por organização.** Cada uma delas é definida para a sua organização, e é ilimitada quando não definida:

| Cota | Janela | Quando atingida |
|---|---|---|
| Requisições | por minuto de relógio UTC, por dia UTC | `429 rate_limited`, `Retry-After` até o próximo minuto ou dia |
| Tokens | por dia UTC, por mês UTC | `429 quota_exceeded` |
| Custo | por dia UTC, por mês UTC | `429 quota_exceeded` |
| Chamadas simultâneas | a qualquer momento | `429 concurrency_limited` |
| Orçamento diário, por provedor e opcionalmente por aplicação | por dia UTC | `429 budget_exhausted`, `Retry-After` até 00:00 UTC |

Uma requisição conta contra os limites de requisições por minuto e por dia assim que é admitida, mesmo que falhe depois. Os limites de tokens e de custo permitem uma chamada que atinja exatamente o limite. A partir do nível de alerta de um orçamento (80% por padrão), as respostas trazem `X-Budget-Warning` antes de as chamadas começarem a ser recusadas.

## Dados e Arquivos

| Limite | Valor |
|---|---|
| Corpo da requisição JSON | 1 MiB (`413 payload_too_large`) |
| Um registro | 900 KiB (`400 record_too_large`) |
| Um campo `json` | 64 KiB |
| Campos por coleção; coleções por banco de dados | 64; 64 |
| Registros por página | 200 (padrão 50) |
| Operações por lote | 100, uma transação |
| Filtro | 2.048 caracteres, 40 valores, profundidade de aninhamento 8 |
| Query string | 16 KiB (`400 invalid_query`) |
| Arquivo ou blob em uma requisição | 100 MiB, com `Content-Length` (`411` sem ele) |
| Arquivo ou blob em partes | 5 GiB; partes de 5 MiB a 100 MiB, numeradas de 1 a 10.000 |
| Caminho do arquivo; prefixo de listagem; metadados do arquivo | 1.024 bytes; 256 bytes; 2 KiB |
| Ouvintes em tempo real por coleção; um evento | 1.000; 512 KiB |
| Página do Registro de atividade | 1 a 500 (padrão 100) |
| Taxa | 600 requisições por minuto por titular de credencial, por localização (`429 rate_limited`) |

O limite de taxa é contado por localização e é um freio, não uma contagem exata.

## Eventos

| Limite | Valor |
|---|---|
| Corpo da requisição | 5 MiB (`413 payload_too_large`) |
| Eventos por publicação | 100 |
| `data` por evento | 16 KiB (`basic`, `reliable`), 32 KiB (`advanced`) |
| Janela de deduplicação de uma `idempotency_key` | 168 horas |
| Assinaturas por espaço de trabalho; padrões por assinatura | 50; 20 |
| Mensagens por pull; reserva do pull | 100; 5 a 300 segundos |
| Tempo de resposta do webhook | 10 segundos |
| Novas tentativas do webhook | a partir de 10 segundos, dobrando até 10 minutos; limite 5 |
| Mensagens mortas mantidas | 30 dias |
| Taxa | 600 chamadas por minuto por credencial, por localização (`429 rate_limited`) |

## Como ficar abaixo dos limites

- **Agrupe**: envie até 100 documentos, operações ou eventos por chamada em vez de um de cada vez.
- **Envie arquivos grandes em partes** em vez de aumentar o tamanho dos corpos.
- **Espere em `429`**: respeite `Retry-After` e adicione jitter para que muitos clientes não tentem novamente no mesmo instante.
- **Defina `max_tokens`** nas chamadas de chat: isso reduz o que cada chamada reserva contra as suas cotas.
- **Observe `X-Budget-Warning`** e o resumo de uso de IA para ver uma cota se aproximando antes de ela se esgotar.

## Veja também

- [Erros](/pt-br/guides/errors/): todos os códigos e a política de novas tentativas.
- [Autenticação](/pt-br/guides/authentication/): credenciais e idempotência.
- Cada página de produto lista os seus próprios limites por completo.