# Limites de taxa e simultaneidade

O Tripo API aplica limites de taxa e limites de simultaneidade para garantir a estabilidade do serviço e o uso justo.

## Limites de taxa

Os limites de taxa restringem o número de solicitações API que você pode fazer em um intervalo de tempo.

### Regras de Limite

- Os limites de taxa são calculados no nível **API Key**
- Os limites variam de acordo com o endpoint. Os endpoints de geração, como `/v3/generation/*`, têm limites mais baixos, enquanto os endpoints de consulta, como `/v3/tasks/*`, têm limites mais altos
- Quando um limite é excedido, API retorna HTTP `429 Too Many Requests` com código de erro `1007`

### Cabeçalhos de resposta

Cada resposta API inclui cabeçalhos de resposta relacionados ao limite de taxa:

| Cabeçalho de resposta | Descrição |
| :-: | :-: |
| `X-RateLimit-Limit` | Número máximo de solicitações permitidas na janela de tempo atual |
| `X-RateLimit-Remaining` | Número de solicitações restantes disponíveis na janela de tempo atual |
| `X-RateLimit-Reset` | Carimbo de data/hora Unix, em segundos, quando a janela de limite de taxa é redefinida |

### Resposta quando a taxa é limitada

```json
{
  "code": 1007,
  "message": "Rate limit exceeded, you've generated too many requests in a short amount of time",
  "suggestion": "Please wait for a while and try again"
}
```

---

## Limites de simultaneidade

Os limites de simultaneidade restringem o número de tarefas que podem ser executadas **simultaneamente** em sua conta. Isso é diferente dos limites de taxa – os limites de taxa limitam a frequência de solicitação, enquanto os limites de simultaneidade limitam as tarefas de execução paralela.

### Como funciona

- A simultaneidade é calculada no nível da **conta** (não por API Key)
- Os limites são aplicados **por categoria de tarefa** — cada categoria tem seu próprio pool de simultaneidade independente
- Quando a simultaneidade de uma categoria está completa, a criação de uma nova tarefa para essa categoria retorna HTTP `429` com o código de erro `2000`
- Tarefas em outras categorias **não são afetadas** — você ainda pode criar tarefas em categorias que tenham vagas disponíveis

### Limites padrão

Todos os usuários começam com uma simultaneidade padrão de **10** por categoria; algumas categorias têm limites diferentes (veja a tabela abaixo).

| Categoria | Tipos de tarefas incluídas | Simultaneidade padrão |
| :-: | :-: | :-: |
| Geração 3D – Série H | texto para modelo (H), imagem para modelo (H), multivisualização para modelo (H) | 10 |
| Geração 3D — Série P | texto para modelo (P), imagem para modelo (P), multivisualização para modelo (P) | 5 |
| Geração de imagem | texto para imagem, imagem para imagem, imagem para multivisualização, edição multivisualização | 1 |
| Animação | auto-rig, rig-check, animação-retarget | 10 |
| Processamento de modelo | textura, conversão de formato, refinar | 5 |
| Operações de malha | segmentação, conclusão, retopologia | 10 |

> **Observação:** Tarefas dentro da mesma categoria compartilham o pool de simultaneidade. Por exemplo, se você tiver 10 tarefas de texto para modelo da série H em execução, não será possível iniciar uma tarefa de imagem para modelo da série H até que uma seja concluída. No entanto, você ainda pode iniciar tarefas da série P ou de geração de imagens.

### Resposta quando a simultaneidade é excedida

```json
{
  "code": 2000,
  "message": "You have exceeded the limit of generation",
  "suggestion": "Try again later. You can also check `Retry-After` header."
}
```

A resposta inclui um cabeçalho `Retry-After` indicando quantos segundos esperar antes de tentar novamente.

### Aumentando a simultaneidade

Para solicitar limites maiores de simultaneidade, entre em contato com nossa equipe pelo canal de suporte. A simultaneidade personalizada pode ser configurada por categoria com base nas suas necessidades de uso.

---

## Lidando com 429 respostas

### Python

```python
import time
import requests

def request_with_backoff(method, url, headers, json=None, max_retries=5):
    for attempt in range(max_retries):
        response = requests.request(method, url, headers=headers, json=json)

        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        reset_at = response.headers.get("X-RateLimit-Reset")

        if retry_after:
            wait = int(retry_after)
        elif reset_at:
            wait = max(int(reset_at) - int(time.time()), 1)
        else:
            wait = 2 ** attempt

        print(f"429 triggered. Waiting {wait} seconds (attempt {attempt + 1})...")
        time.sleep(wait)

    raise Exception("Maximum retry attempts exhausted")
```

### JavaScript

```javascript
async function requestWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = response.headers.get("Retry-After");
    const resetAt = response.headers.get("X-RateLimit-Reset");
    const wait = retryAfter
      ? Number(retryAfter)
      : resetAt
        ? Math.max(Number(resetAt) - Math.floor(Date.now() / 1000), 1)
        : 2 ** attempt;

    console.log(`429 triggered. Waiting ${wait} seconds (attempt ${attempt + 1})...`);
    await new Promise(resolve => setTimeout(resolve, wait * 1000));
  }

  throw new Error("Maximum retry attempts exhausted");
}
```

## Melhores Práticas

- **Implementar novas tentativas de espera exponencial**: espere 1 segundo inicialmente, duplique a espera a cada vez e limite a espera máxima a 32 segundos
- **Prefira os cabeçalhos `Retry-After` e `X-RateLimit-Reset`**: aguarde precisamente até que a janela de limite seja redefinida
- **Projete para simultaneidade em nível de categoria**: distribua cargas de trabalho entre categorias quando possível — a geração de imagens e a geração 3D têm pools separados
- **Use APIs em lote**: use `POST /v3/tasks/list` em vez de várias solicitações `GET /v3/tasks/{task_id}`
- **Pesquise com sabedoria**: ao aguardar a conclusão da tarefa, pesquise em intervalos razoáveis (a cada 1–2 segundos) em vez de sobrecarregar o endpoint da consulta