Bonnes pratiques

Suivez ces recommandations pour créer des intégrations fiables, rentables et faciles à maintenir.

Efficacité des crédits

Vérifiez votre solde avant les traitements en masse

Avant de déclencher une opération à fort volume, vérifiez que vous disposez de suffisamment de crédits. L'endpoint Usage est gratuit et retourne votre solde actuel en temps réel.

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

Activez le Rechargement automatique pour recharger automatiquement votre solde lorsqu'il passe sous un seuil, afin que vos flux de travail continuent sans interruption.

Évitez les appels redondants

Mettez en cache les résultats de votre côté lorsque les données sous-jacentes sont peu susceptibles de changer entre les requêtes. Récupérer des entrées identiques gaspille des crédits.

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
}

N'appelez que ce dont vous avez besoin

Chaque endpoint a un coût en crédits défini sur la page Crédits. Préférez les endpoints moins coûteux lorsqu'une réponse complète n'est pas nécessaire.

Authentification

Stockez les clés dans des variables d'environnement

Ne codez jamais en dur votre clé API dans le code source. Utilisez des variables d'environnement et chargez-les à l'exécution.

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

Utilisez des clés distinctes par environnement

Créez des clés API distinctes pour le développement, la pré-production et la production dans votre tableau de bord. Cela vous permet de révoquer ou de faire tourner une clé compromise sans affecter les autres environnements.

Faites tourner les clés régulièrement

Traitez les clés API comme des mots de passe. Définissez une date d'expiration sur les clés sensibles et faites-les tourner selon un calendrier régulier depuis la section Clés API des paramètres de votre compte.

Gestion des erreurs

Vérifiez toujours le code de statut HTTP

Ne supposez pas qu'une requête a réussi. Chaque réponse doit être vérifiée par rapport à son code de statut HTTP avant de traiter le corps. Consultez le guide Gestion des erreurs pour une analyse complète.

Réessayez les erreurs transitoires

Les erreurs serveur (500) et les délais d'attente réseau sont transitoires. Implémentez un backoff exponentiel pour réessayer automatiquement :

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

Ne réessayez jamais un 402 sans recharger

Une réponse 402 Payment Required signifie que votre solde est vide. Réessayer immédiatement n'aidera pas. Ajoutez des crédits depuis votre tableau de bord ou activez le Rechargement automatique.

Limites de débit

Étalez les requêtes dans le temps

Si vous devez envoyer un grand nombre d'appels, distribuez-les dans le temps plutôt que de les envoyer tous en même temps. Un simple délai entre les itérations évite d'atteindre les limites de débit.

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

Surveillez la réponse 401 Rate Limit Exceeded

En cas de limitation de débit, l'API retourne 401 avec le statut Rate Limit Exceeded. Attendez avant de réessayer. Envisagez de mettre à niveau votre plan si vous atteignez régulièrement ces limites.

Sécurité

Ne faites jamais d'appels API depuis le navigateur

Votre clé API serait visible par quiconque inspecte l'onglet réseau. Faites toujours transiter les appels par votre propre serveur.

Browser → Your backend → ChartQuery API

Validez et assainissez les entrées

Si votre application accepte des paramètres fournis par l'utilisateur qui sont transmis à l'API (URLs, requêtes de recherche, etc.), assainissez-les pour éviter les injections ou les comportements inattendus.

Surveillance

Suivez la consommation de crédits

Interrogez l'endpoint Usage selon un calendrier (par exemple quotidiennement) et alertez lorsque la consommation dépasse un seuil. Cela évite les mauvaises surprises en fin de période de facturation.

Enregistrez le contexte des requêtes

Conservez le code de statut HTTP et un horodatage pour chaque appel API. Cela facilite l'audit de la consommation de crédits et le débogage des échecs après coup.

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
}

Liste de contrôle

Utilisez cette liste de contrôle avant de passer en production :

• Clé API stockée dans une variable d'environnement, pas dans le code source
• Clés distinctes pour le développement et la production
• Codes de statut HTTP vérifiés sur chaque réponse
• Logique de nouvelle tentative avec backoff exponentiel pour les erreurs 500
• Aucune nouvelle tentative sur 402 sans ajout de crédits
• Gestion des limites de débit en place
• Solde de crédits surveillé et alertes configurées
• Rechargement automatique activé (ou un processus de rechargement manuel défini)
• Tous les appels API transitent par votre backend

Voir aussi : Gestion des erreurs pour une liste complète des codes de statut et Glossaire pour les définitions des termes.