Limites¶

Esta página documenta todos os rate limits, limites de tamanho e outras restrições da API do Nodexa.

Limites de Request¶

Tools¶

Limite	Valor
Máximo de tools por request	128
Comprimento máximo do nome da tool	64 caracteres
Caracteres permitidos no nome	Alfanumérico (`a-z`, `A-Z`, `0-9`), underscore (`_`), hífen (`-`)
Nomes de tools devem ser únicos	Sim — dentro de uma única request

Os nomes das tools devem corresponder ao padrão: ^[a-zA-Z0-9_-]{1,64}$

Exemplos:

get_weather — válido
lookup-order — válido
myTool123 — válido
my tool — inválido (espaço não é permitido)
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa — inválido (65 caracteres, excede o limite)

Input¶

Limite	Valor
Máximo de mensagens de input no array	Sujeito à janela de contexto do LLM de base
Comprimento máximo do campo `instructions`	Sujeito à janela de contexto do LLM de base

Limites de janela de contexto

O Nodexa não impõe limites próprios de tokens no input. Porém, a request vai falhar se a contagem total de tokens exceder a janela de contexto do modelo LLM que respalda o Agente Especialista ativo. Os limites de tokens variam por provedor e modelo (por exemplo, 128k tokens para GPT-4o, 200k para Claude 3.5 Sonnet). Fale com seu administrador Nodexa para saber os modelos em uso na sua instância.

Limites de User Claims¶

Limite	Valor
Tamanho máximo de `claimValue`	64KB (como JSONB)
Máximo de claims por request bulk	50
Número de claims por usuário	Sem limite imposto

Limites de Memória¶

Limite	Valor
Número de itens de memória por par usuário/assistant	Gerenciado pela plataforma — contate seu administrador
Comprimento do conteúdo de itens de memória	Sujeito à configuração da plataforma

Limites de API Key¶

Limite	Valor
Chaves por organização	Configurado pelo seu administrador
Expiração de chave	As chaves não expiram automaticamente — precisam ser revogadas manualmente

Rate Limits¶

Os rate limits são configurados por organização pelo administrador do Nodexa e dependem do seu plano. Quando você excede um rate limit, a API retorna 429 Too Many Requests.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "You have exceeded the rate limit. Please wait before retrying."
  }
}

A resposta inclui um header Retry-After indicando quantos segundos esperar:

Retry-After: 5

Tratando Rate Limits¶

async function callWithRateLimitRetry(fn, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429) {
        const retryAfter = parseInt(err.headers?.['retry-after'] ?? '1', 10);
        console.warn(`Rate limited. Retrying in ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries exceeded');
}

Limites de Conexão de Streaming¶

Limite	Valor
Intervalo de heartbeat	15 segundos (comentário enviado se nenhum dado por 15s)
Duração máxima do stream	Sujeito à configuração de proxy/load balancer da sua plataforma

Timeouts de proxy e CDN

Se sua infraestrutura usa um proxy reverso (Nginx, HAProxy) ou CDN (Cloudflare, CloudFront), certifique-se de que os timeouts de conexão ociosa estejam acima de 15 segundos. O heartbeat foi projetado para manter conexões ativas em intermediários com timeout de ociosidade de até 15 segundos. Se o seu proxy tiver um timeout menor, ajuste-o.

Operações em Massa¶

Operação	Limite
`POST /v1/user-claims/bulk`	Máximo de 50 claims por request

Para lotes maiores, divida as requests em blocos de 50:

async function bulkUpsertClaims(claims) {
  const CHUNK_SIZE = 50;

  for (let i = 0; i < claims.length; i += CHUNK_SIZE) {
    const chunk = claims.slice(i, i + CHUNK_SIZE);
    await fetch('/v1/user-claims/bulk', {
      method: 'POST',
      headers: {
        'x-api-key': process.env.NODEXA_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ claims: chunk }),
    });
  }
}

Referência de Validação¶

Validação de Nome de Tool¶

// Verifica se um nome de tool é válido
function isValidToolName(name) {
  return /^[a-zA-Z0-9_-]{1,64}$/.test(name);
}

isValidToolName('get_weather'); // true
isValidToolName('lookup-order'); // true
isValidToolName('my tool'); // false (espaço)
isValidToolName('a'.repeat(65)); // false (muito longo)
isValidToolName(''); // false (vazio)

Tamanho do Valor de Claim¶

// Estima o tamanho do valor de claim antes de submeter
function isClaimValueWithinLimit(value) {
  const json = JSON.stringify(value);
  const bytes = new TextEncoder().encode(json).length;
  return bytes <= 64 * 1024; // 64KB
}

import json

def is_claim_value_within_limit(value) -> bool:
    json_str = json.dumps(value)
    return len(json_str.encode('utf-8')) <= 64 * 1024  # 64KB