Rate limit & CORS

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

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

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

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.

O que acontece quando estoura

A API responde com HTTP 429 Too Many Requests:

{
  "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

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.

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.

Métodos e headers aceitos

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

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:

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

Implemente backoff com base em X-RateLimit-Remaining para não ser bloqueado.

Trate HTTP 429 com re-tentativa após X-RateLimit-Reset.

Se usa browser, peça ao suporte para adicionar sua origem na allowlist.

Para WebSocket em browser, passe o token via ?token= na URL.

Primeiros passos

Fundamentos

MCP

Rate limit & CORS

Rate limit

Cabeçalhos de rate limit

O que acontece quando estoura

Exemplo de tratamento

CORS

Origens permitidas

Métodos e headers aceitos

Sem cookies

WebSocket em navegador

Checklist

​Rate limit

​Cabeçalhos de rate limit

​O que acontece quando estoura

​Exemplo de tratamento

​CORS

​Origens permitidas

​Métodos e headers aceitos

​Sem cookies

​WebSocket em navegador

​Checklist

Rate limit

Cabeçalhos de rate limit

O que acontece quando estoura

Exemplo de tratamento

CORS

Origens permitidas

Métodos e headers aceitos

Sem cookies

WebSocket em navegador

Checklist