> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Limites de débit

> Comprenez les limites de l’API par équipe, les en-têtes de limite de débit et la gestion de Retry-After.

Les limites s’appliquent **par équipe**, sur l’ensemble des jetons d’API de cette équipe.

## Limites actuelles

Deux fenêtres s’appliquent simultanément à chaque requête :

| Fenêtre | Limite |
| - | - |
| Par minute (pic) | 1 000 requêtes par minute |
| Par jour (plafond quotidien) | 20 000 requêtes par jour |

Une requête n’est acceptée que si **les deux** fenêtres ont encore du budget. Si l’une d’elles est épuisée, l’API renvoie `429 Too Many Requests`.

<Note>
  Pour discuter d’une autre limite pour une charge prévue, écrivez à [team@qwairy.co](mailto:team@qwairy.co) en indiquant le volume de requêtes attendu.
</Note>

## En-têtes de limite de débit

Après une authentification réussie, les réponses de l’API incluent des en-têtes pour les deux fenêtres. Une réponse `429` inclut aussi `Retry-After`.

| En-tête | Description |
| - | - |
| `X-RateLimit-Limit` | Plafond de requêtes par minute |
| `X-RateLimit-Remaining` | Requêtes restantes dans la fenêtre de la minute en cours |
| `X-RateLimit-Reset` | Horodatage ISO 8601 de réinitialisation de la fenêtre par minute |
| `X-RateLimit-Daily-Limit` | Plafond de requêtes par jour |
| `X-RateLimit-Daily-Remaining` | Requêtes restantes dans la fenêtre du jour en cours |
| `X-RateLimit-Daily-Reset` | Horodatage ISO 8601 de réinitialisation de la fenêtre quotidienne |
| `Retry-After` | Secondes à attendre avant de réessayer, selon la limite effectivement atteinte (présent uniquement sur `429`) |

### Exemple d’en-têtes

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 2026-04-07T09:13:00.000Z
X-RateLimit-Daily-Limit: 20000
X-RateLimit-Daily-Remaining: 4211
X-RateLimit-Daily-Reset: 2026-04-08T00:00:00.000Z
```

<Warning>
  Surveillez les deux fenêtres. Une requête peut être rejetée parce que le plafond quotidien est épuisé alors qu’il reste du budget par minute, et inversement.
</Warning>

## Gérer les limites de débit

Lorsqu’une fenêtre est dépassée, l’API renvoie `429 Too Many Requests` avec un corps qui indique la fenêtre atteinte :

```json theme={null}
{
  "error": "Too Many Requests",
  "limit": "daily",
  "message": "Daily rate limit (20000/day) exceeded. Please try again in 32451 seconds.",
  "retryAfter": 32451
}
```

Le champ `limit` vaut `"burst"` ou `"daily"`. Respectez `Retry-After`, calculé à partir de la fenêtre qui a bloqué la requête.

### Bonnes pratiques de nouvelle tentative

<CardGroup cols={2}>
  <Card title="Respectez Retry-After" icon="clock">
    Utilisez l’en-tête `Retry-After` tel quel. Il reflète déjà la fenêtre (minute ou jour) réellement bloquante.
  </Card>

  <Card title="Surveillez les deux en-têtes de solde" icon="gauge">
    Surveillez `X-RateLimit-Remaining` et `X-RateLimit-Daily-Remaining` pour ralentir avant d’être bloqué.
  </Card>

  <Card title="Mettez les réponses en cache" icon="database">
    Conservez et réutilisez les données qui changent peu (marques, concurrents, Topics).
  </Card>

  <Card title="Regroupez et filtrez" icon="layer-group">
    Utilisez les filtres de requête (`provider`, `period`, `limit`) pour ne récupérer que les données utiles.
  </Card>
</CardGroup>

### Logique de nouvelle tentative

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 10) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response;

    // Retry-After points at the blocking window
    // (minute or day window), not just the minute reset.
    const retryAfterSec = Number(response.headers.get('Retry-After') ?? '60');
    const waitMs = Math.max(retryAfterSec * 1000, 1000);

    const body = await response.clone().json().catch(() => ({}));
    console.warn(
      `Rate limited on ${body.limit ?? 'unknown'} window. Retrying in ${waitMs}ms...`
    );

    await new Promise((r) => setTimeout(r, waitMs));
  }

  throw new Error('Max retries exceeded');
}
```

<Tip>
  Si vous obtenez `"limit": "daily"` lors d’une nouvelle tentative, attendre dans le même processus aide rarement : la fenêtre quotidienne peut se rouvrir dans plusieurs heures. Enregistrez l’horodatage `X-RateLimit-Daily-Reset` et replanifiez la tâche au lieu de bloquer un worker.
</Tip>

## Réduire l’utilisation de l’API

### Utiliser les paramètres de filtre

Plutôt que de tout récupérer puis de filtrer côté client, utilisez les paramètres de requête :

```bash theme={null}
# Fetch all answers, then filter in code
GET /api/v1/brands/{brandId}/answers

# Filter at the API level
GET /api/v1/brands/{brandId}/answers?provider=chatgpt&hasSelfMention=true&limit=50
```

### Mettre en cache les données stables

Ne gardez les données en cache que le temps que votre intégration peut tolérer des données périmées :

* **Liste des marques** : change quand l’accès aux marques change
* **Liste des concurrents** : change avec la configuration et les données observées
* **Topics et Tags** : changent quand la configuration du workspace change

### Utiliser des plages de dates

Limitez la récupération aux périodes utiles :

```bash theme={null}
# Bound an otherwise unbounded request to the last 7 days
GET /api/v1/brands/{brandId}/performance?period=7
```

## Demander des limites plus élevées

Écrivez à [team@qwairy.co](mailto:team@qwairy.co) en décrivant votre cas d’usage et le volume attendu. Toute modification dépend de la charge et de la configuration du compte.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.