> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limit & CORS

> Limites de requisições por minuto e regras de CORS para uso em navegador

## Rate limit

Para manter a estabilidade do serviço, a RyzeAPI aplica um limite de requisições por minuto. O limite é contado **por token**: todos que usam o mesmo token compartilham o mesmo balde.

| Tipo de requisição                              | Limite padrão                  |
| ----------------------------------------------- | ------------------------------ |
| Maioria dos endpoints                           | **100 requisições por minuto** |
| Criação de instância (`POST /api/instance/new`) | **20 requisições por minuto**  |

<Info>
  Se você precisar de um limite maior para sua conta, entre em contato com o suporte.
</Info>

### Cabeçalhos de rate limit

**Todas as respostas** (inclusive as bem-sucedidas) trazem três cabeçalhos que permitem ao seu cliente se adaptar:

| Header                  | Significado                                         |
| ----------------------- | --------------------------------------------------- |
| `X-RateLimit-Limit`     | Limite máximo no período atual (ex.: `100`)         |
| `X-RateLimit-Remaining` | Quantas requisições ainda cabem                     |
| `X-RateLimit-Reset`     | Timestamp Unix (segundos) de quando o contador zera |

<Tip>
  Use `X-RateLimit-Remaining` para implementar backoff exponencial **antes** de bater no limite. Por exemplo: quando ficar abaixo de 10, espere um pouco antes da próxima chamada.
</Tip>

### O que acontece quando estoura

A API responde com `HTTP 429 Too Many Requests`:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Try again later."
  }
}
```

Os cabeçalhos `X-RateLimit-*` continuam sendo enviados, use `X-RateLimit-Reset` para saber quando pode tentar de novo.

### Exemplo de tratamento

```javascript theme={null}
async function callAPI(path, options = {}) {
  const res = await fetch(`https://ryzeapi.cloud${path}`, options);

  // Se estourou o limite, espere até o reset
  if (res.status === 429) {
    const resetAt = parseInt(res.headers.get("X-RateLimit-Reset"), 10) * 1000;
    const waitMs = Math.max(1000, resetAt - Date.now());
    await new Promise(r => setTimeout(r, waitMs));
    return callAPI(path, options); // tenta novamente
  }

  // Backoff preventivo: se estiver quase no limite, desacelera
  const remaining = parseInt(res.headers.get("X-RateLimit-Remaining"), 10);
  if (remaining < 10) {
    await new Promise(r => setTimeout(r, 500));
  }

  return res.json();
}
```

## CORS

Se você está chamando a API **de um navegador** (JavaScript rodando em uma página web), precisa se atentar ao CORS.

### Origens permitidas

A RyzeAPI aceita requisições vindas apenas das origens autorizadas para a sua conta. Origens não autorizadas recebem o erro clássico de CORS no console do navegador:

```
Access to fetch at 'https://ryzeapi.cloud/...' from origin 'https://meusite.com'
has been blocked by CORS policy.
```

<Tip>
  Se sua aplicação frontend precisa chamar a RyzeAPI, peça ao suporte para adicionar a sua origem (`https://meusite.com`) na allowlist da sua conta.
</Tip>

### Métodos e headers aceitos

A API responde ao preflight (`OPTIONS`) com os seguintes cabeçalhos:

```http theme={null}
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, token
Access-Control-Expose-Headers: Content-Length
```

Você pode enviar requisições com qualquer método HTTP usado pela API e com os headers `Content-Type`, `Authorization` ou `token`.

### Sem cookies

A RyzeAPI **não usa cookies** para autenticação, o token vai no header `token`. Por isso, não é necessário (e não é suportado) enviar `credentials: "include"` nas requisições `fetch`.

## WebSocket em navegador

Como JavaScript no browser não permite customizar headers em `new WebSocket(...)`, a única forma de autenticar é pela query string:

```javascript theme={null}
const ws = new WebSocket(
  `wss://ryzeapi.cloud/ws/$Instance_Name?token=${instanceToken}`
);
```

O WebSocket também segue a allowlist de origens da sua conta.

## Checklist

<Check>Implemente backoff com base em `X-RateLimit-Remaining` para não ser bloqueado.</Check>
<Check>Trate `HTTP 429` com re-tentativa após `X-RateLimit-Reset`.</Check>
<Check>Se usa browser, peça ao suporte para adicionar sua origem na allowlist.</Check>
<Check>Para WebSocket em browser, passe o token via `?token=` na URL.</Check>