Rate limiting API immobilière

Pourquoi limiter les requêtes

Sans rate limit, un client mal codé peut consommer 100 % des ressources de l'API et pénaliser tous les autres. Le rate limiting est donc à la fois une protection technique et une question d'équité de service.

Les algorithmes courants

Limites Ts-Immo par plan

Les en-têtes de réponse

Chaque réponse Ts-Immo inclut trois en-têtes pour piloter le throttling côté client.

HTTP/1.1 200 OK
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 184
X-RateLimit-Reset: 1716120000
Content-Type: application/json

Code 429 et retry

Quand la limite est dépassée, l'API renvoie un 429 Too Many Requests avec un en-tête Retry-After indiquant le nombre de secondes à attendre. Votre client doit respecter cette valeur.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options)
    if (res.status !== 429) return res
    const retryAfter = parseInt(res.headers.get('Retry-After') || '1')
    await new Promise(r => setTimeout(r, retryAfter * 1000))
  }
  throw new Error('Rate limit exceeded after retries')
}

Bonnes pratiques côté client

• Throttler proactivement en fonction de X-RateLimit-Remaining.
• Mettre en cache local les réponses qui ne changent pas (agencies, types).
• Préférer un cycle nocturne pour les imports massifs.
• Utiliser updated_since pour limiter le volume.
• Implémenter un backoff exponentiel en cas de 429 répétés.

Demander un quota supérieur

Pour les usages spécifiques (intégrateur, agrégateur, importation initiale massive), des quotas custom sont disponibles sur demande via le support. Comptez 24 à 48 h pour l'analyse et la validation du besoin.