Buenas prácticas

Siga estas pautas para crear integraciones fiables, rentables y fáciles de mantener.

Eficiencia de créditos

Compruebe su saldo antes de operaciones masivas

Antes de iniciar una operación de alto volumen, verifique que tiene suficientes créditos. El endpoint Uso es gratuito y devuelve su saldo actual en tiempo real.

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

Active la Recarga automática para recargar su saldo automáticamente cuando caiga por debajo de un umbral, de modo que sus flujos de trabajo continúen sin interrupciones.

Evite las llamadas redundantes

Almacene en caché los resultados cuando los datos subyacentes no vayan a cambiar entre solicitudes. Recuperar entradas idénticas desperdicia 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
}

Llame solo lo que necesite

Cada endpoint tiene un coste en créditos definido en la página Créditos. Prefiera los endpoints más ligeros cuando no necesite una respuesta completa.

Autenticación

Almacene las claves en variables de entorno

Nunca codifique su clave API directamente en el código fuente. Use variables de entorno y cárguelas en tiempo de ejecución.

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 claves separadas por entorno

Cree claves API distintas para desarrollo, preproducción y producción en su panel de control. Esto le permite revocar o rotar una clave comprometida sin afectar a los demás entornos.

Rote las claves periódicamente

Trate las claves API como contraseñas. Establezca una fecha de expiración en las claves sensibles y rótelas según un calendario regular desde la sección Claves API de los ajustes de su cuenta.

Gestión de errores

Compruebe siempre el código de estado HTTP

No asuma que una solicitud se completó correctamente. Verifique el código de estado HTTP de cada respuesta antes de procesar el cuerpo. Consulte la guía Gestión de errores para un análisis completo.

Reintente los errores transitorios

Los errores del servidor (500) y los tiempos de espera de red son transitorios. Implemente backoff exponencial para reintentar automáticamente:

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 reintente un 402 sin recargar

Una respuesta 402 Payment Required significa que su saldo está vacío. Reintentar inmediatamente no ayudará. Añada créditos desde su panel de control o active la Recarga automática.

Límites de tasa

Distribuya las solicitudes en el tiempo

Si necesita enviar un gran número de llamadas, distribúyalas en el tiempo en lugar de enviarlas todas a la vez. Un simple retraso entre iteraciones evita alcanzar los límites de tasa.

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))
}

Monitoree la respuesta 401 Rate Limit Exceeded

Cuando se alcanza el límite de tasa, la API devuelve 401 con el estado Rate Limit Exceeded. Espere antes de reintentar. Considere actualizar su plan si alcanza los límites con frecuencia.

Seguridad

Nunca realice llamadas API desde el navegador

Su clave API sería visible para cualquiera que inspeccione la pestaña de red. Siempre enrute las llamadas a través de su propio servidor.

Browser → Your backend → ChartQuery API

Valide y sanee las entradas

Si su aplicación acepta parámetros proporcionados por el usuario que se pasan a la API (URLs, consultas de búsqueda, etc.), sáneelos para evitar inyecciones o comportamientos inesperados.

Monitoreo

Rastree el consumo de créditos

Consulte el endpoint Uso según un calendario (p. ej. diariamente) y alerte cuando el consumo supere un umbral. Esto evita sorpresas al final del período de facturación.

Registre el contexto de las solicitudes

Almacene el código de estado HTTP y una marca de tiempo para cada llamada API. Esto facilita auditar el consumo de créditos y depurar fallos a posteriori.

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 verificación

Use esta lista antes de pasar a producción:

• Clave API almacenada en una variable de entorno, no en el código fuente
• Claves separadas para desarrollo y producción
• Códigos de estado HTTP comprobados en cada respuesta
• Lógica de reintento con backoff exponencial para errores 500
• Sin reintentos en 402 sin añadir créditos primero
• Gestión de límites de tasa implementada
• Saldo de créditos monitorizado y alertas configuradas
• Recarga automática activada (o un proceso de recarga manual definido)
• Todas las llamadas API enrutadas a través de su backend

Véase también: Gestión de errores para una lista completa de códigos de estado y Glosario para definiciones de términos.