Erros e Rate Limiting

Formato de Erro

Todos os erros seguem o mesmo formato:

{
  "statusCode": 400,
  "message": "Descrição do erro",
  "timestamp": "2026-02-20T18:00:00.000Z",
  "path": "/otc/quote"
}

Para erros de validação, o campo errors lista os problemas encontrados:

{
  "statusCode": 400,
  "message": "Erro de validação",
  "errors": [
    "market must be a string",
    "amount must be a positive number"
  ],
  "timestamp": "2026-02-20T18:00:00.000Z",
  "path": "/otc/quote"
}

Códigos de Status

Código	Significado	Quando ocorre
`200`	OK	Requisição bem-sucedida
`201`	Created	Registro criado com sucesso
`400`	Bad Request	Dados inválidos, saldo insuficiente, cotação expirada
`401`	Unauthorized	Token ausente, inválido ou expirado
`404`	Not Found	Recurso não encontrado (moeda, transação)
`409`	Conflict	Duplicidade (email ou documento já cadastrado)
`423`	Locked	Valor abaixo do mínimo de negociação
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Erro interno

Rate Limiting

A API limita requisições para garantir estabilidade:

Parâmetro	Valor
Limite	100 requisições
Janela	60 segundos
Escopo	Por IP

Headers de Rate Limit

Em cada resposta, os seguintes headers são retornados:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1693940307

Ao Exceder o Limite

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Recomendação: Implemente backoff exponencial. Aguarde o tempo indicado em X-RateLimit-Reset antes de tentar novamente.

Tratamento Recomendado

async function apiCall(url, options) {
  const response = await fetch(url, options);

  if (response.status === 401) {
    // Token expirado — renovar e tentar novamente
    await refreshToken();
    return apiCall(url, options);
  }

  if (response.status === 429) {
    // Rate limited — aguardar e tentar novamente
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitMs = (Number(resetTime) - Date.now() / 1000) * 1000;
    await sleep(Math.max(waitMs, 1000));
    return apiCall(url, options);
  }

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return response.json();
}