Melhores práticas

Siga estas diretrizes para criar integrações confiáveis, econômicas e fáceis de manter.

Eficiência de créditos

Verifique seu saldo antes de operações em lote

Antes de disparar uma operação de alto volume, verifique se você tem créditos suficientes. O endpoint Uso é gratuito e retorna seu saldo atual em tempo real.

curl "https://api.chartquery.com/v1/usage" \
  -H "x-api-key: YOUR_API_KEY"

Ative a Recarga automática para recarregar automaticamente seu saldo quando ele cair abaixo de um limite, para que seus fluxos de trabalho continuem sem interrupção.

Evite chamadas redundantes

Armazene em cache os resultados do seu lado sempre que os dados subjacentes não forem mudar entre as solicitações. Buscar entradas idênticas desperdiça créditos.

const cache = new Map<string, unknown>()

async function fetchCached(key: string, fetcher: () => Promise<unknown>) {
  if (cache.has(key)) return cache.get(key)
  const result = await fetcher()
  cache.set(key, result)
  return result
}

Chame apenas o que precisa

Cada endpoint tem um custo em créditos definido na página Créditos. Prefira endpoints mais leves quando uma resposta completa não for necessária.

Autenticação

Armazene chaves em variáveis de ambiente

Nunca codifique sua chave de API diretamente no código-fonte. Use variáveis de ambiente e carregue-as em tempo de execução.

const apiKey = process.env.CHARTQUERY_API_KEY
if (!apiKey) throw new Error("API key is not set")

import os
api_key = os.environ["CHARTQUERY_API_KEY"]

$apiKey = getenv('CHARTQUERY_API_KEY');

apiKey := os.Getenv("CHARTQUERY_API_KEY")

Use chaves separadas por ambiente

Crie chaves de API distintas para desenvolvimento, staging e produção no seu painel de controle. Isso permite revogar ou rotacionar uma chave comprometida sem afetar outros ambientes.

Rotacione chaves periodicamente

Trate chaves de API como senhas. Defina uma data de expiração em chaves sensíveis e rotacione-as regularmente na seção Chaves de API das configurações da sua conta.

Tratamento de erros

Sempre verifique o código de status HTTP

Não assuma que uma solicitação foi bem-sucedida. Cada resposta deve ser verificada pelo código de status HTTP antes de processar o corpo. Consulte o guia de Tratamento de erros para uma análise completa.

Tente novamente em erros transitórios

Erros de servidor (500) e timeouts de rede são transitórios. Implemente backoff exponencial para tentar novamente automaticamente:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const res = await fetch(url, options)
      if (res.status === 500 && attempt < maxRetries) {
        await new Promise(r => setTimeout(r, 500 * 2 ** attempt))
        continue
      }
      return res
    } catch {
      if (attempt === maxRetries) throw new Error("Max retries reached")
      await new Promise(r => setTimeout(r, 500 * 2 ** attempt))
    }
  }
}

Nunca tente novamente um 402 sem recarregar

Uma resposta 402 Payment Required significa que seu saldo está vazio. Tentar a mesma chamada novamente imediatamente não ajudará. Adicione créditos no seu painel de controle ou ative a Recarga automática.

Limites de taxa

Distribua as solicitações ao longo do tempo

Se você precisar enviar um grande número de chamadas, distribua-as ao longo do tempo em vez de enviá-las todas de uma vez. Um simples atraso entre iterações evita atingir os limites de taxa.

const DELAY_MS = 100 // adjust based on your plan

for (const item of items) {
  await processItem(item)
  await new Promise(r => setTimeout(r, DELAY_MS))
}

Monitore a resposta 401 Rate Limit Exceeded

Quando o limite de taxa é atingido, a API retorna 401 com o status Rate Limit Exceeded. Aguarde antes de tentar novamente. Considere atualizar seu plano se você atingir os limites com frequência.

Segurança

Nunca faça chamadas de API a partir do navegador

Sua chave de API ficaria visível para qualquer pessoa que inspecione a aba de rede. Sempre roteie as chamadas através do seu próprio servidor.

Browser → Your backend → ChartQuery API

Valide e higienize as entradas

Se sua aplicação aceitar parâmetros fornecidos pelo usuário que são passados à API (URLs, consultas de pesquisa, etc.), higienize-os para evitar injeção ou comportamento inesperado.

Monitoramento

Acompanhe o consumo de créditos

Consulte o endpoint Uso regularmente (p. ex. diariamente) e alerte quando o consumo exceder um limite. Isso evita surpresas no final do período de faturamento.

Registre o contexto das solicitações

Armazene o código de status HTTP e um carimbo de data/hora para cada chamada de API. Isso facilita auditar o consumo de créditos e depurar falhas após o ocorrido.

async function apiCall(endpoint: string, params: Record<string, string>) {
  const url = new URL(`https://api.chartquery.com${endpoint}`)
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v))

  const res = await fetch(url.toString(), {
    headers: { "x-api-key": process.env.API_KEY! },
  })

  console.log(JSON.stringify({
    endpoint,
    status: res.status,
    billed: res.status === 200 || res.status === 201,
    timestamp: new Date().toISOString(),
  }))

  return res
}

Lista de verificação

Use esta lista antes de ir para produção:

• Chave de API armazenada em variável de ambiente, não no código-fonte
• Chaves separadas para desenvolvimento e produção
• Códigos de status HTTP verificados em cada resposta
• Lógica de nova tentativa com backoff exponencial para erros 500
• Sem novas tentativas em 402 sem adicionar créditos primeiro
• Tratamento de limites de taxa implementado
• Saldo de créditos monitorado e alertas configurados
• Recarga automática ativada (ou processo de recarga manual definido)
• Todas as chamadas de API roteadas através do seu backend

Veja também: Tratamento de erros para uma lista completa de códigos de status e Glossário para definições de termos.