---
title: Idempotence, pagination et quotas
description: Réessayer une création sans doublon avec Idempotency-Key, parcourir les listes avec after et respecter le quota par clé et par projet.
---

# Idempotence, pagination et quotas

Trois règles rendent une intégration robuste : chaque création porte une clé d'idempotence, les listes se parcourent par curseur, et le débit reste sous le quota de la clé.

**Qui peut le faire** : tout outil qui appelle l'API.

## Idempotence des créations

Les deux créations, `POST …/runs` et `POST …/audits`, exigent l'en-tête `Idempotency-Key`.

| Règle | Détail |
| --- | --- |
| Format | 8 à 128 caractères ASCII visibles (sans espace) |
| Portée | propriétaire, clé API, projet et route |
| Même valeur, même corps | la première réponse est rejouée pendant 24 heures, avec `Idempotent-Replayed: true` |
| Même valeur, autre corps | `409 conflict` |
| En-tête absent ou invalide | `422 invalid_request` |
| Deux requêtes identiques simultanées | un seul effet |

Le corps est comparé après normalisation : l'ordre des champs JSON n'a pas d'importance.

```bash
curl -sS -i -X POST https://maintain.example/api/v1/projects/<projectId>/runs \
  -H "Authorization: Bearer $MAINTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: issue-42-2026-11-19" \
  -d '{"repositoryId":"<repositoryId>","issueNumber":42}'
```

```http
HTTP/1.1 202 Accepted
Location: /api/v1/runs/<runId>
Idempotent-Replayed: false
Cache-Control: no-store
```

### Choisir la valeur

Dérivez la valeur de l'**intention**, pas de l'essai. Exemples : `issue-42-2026-11-19`, `audit-hebdo-2026-w47`, `gha-<identifiant du workflow>`. Après une coupure réseau, renvoyez exactement la même requête avec la même valeur : vous obtenez la réponse d'origine, sans second effet.

> [!WARNING]
> Une valeur aléatoire régénérée à chaque essai annule la protection : chaque essai devient une nouvelle demande.

### Verrous métier en plus

L'idempotence ne remplace pas les règles métier. Une issue n'a qu'une exécution originale : même après 24 heures, redemander la même issue renvoie `409`. Un audit déjà en file ou en cours pour un dépôt est renvoyé tel quel au lieu d'en créer un second. Pendant un arrêt global, les créations sont acceptées et attendent la levée (champ `waiting`) : voir [Erreurs](05-erreurs.md#arret-global).

L'annulation `POST /api/v1/runs/<runId>/cancel` est idempotente par nature : la répéter ne change rien et n'exige pas d'`Idempotency-Key`.

## Pagination

Les listes sont triées par identifiant. Chaque page renvoie un champ `next` : passez sa valeur dans le paramètre `after` pour obtenir la page suivante. `next: null` signale la fin.

| Route | Taille de page | Paramètre `limit` |
| --- | --- | --- |
| `GET /api/v1/projects` | 50 | non accepté |
| `GET …/repositories` | 1 à 50, 50 par défaut | oui |
| `GET …/runs` | 1 à 50, 50 par défaut | oui |
| `GET …/audits` | 30 | non accepté |
| `GET …/usage` (entrées) | 100 | non accepté |

Un `limit` hors bornes, ou un `after` qui n'est pas un identifiant valide, renvoie `422`. Pour `/usage`, `after` est un curseur opaque : réutilisez la valeur `next` telle quelle.

```bash
after=""
while :; do
  page=$(curl -sS "https://maintain.example/api/v1/projects/<projectId>/runs?limit=50${after:+&after=$after}" \
    -H "Authorization: Bearer $MAINTAIN_API_KEY")
  echo "$page" | jq -r '.runs[] | "\(.id) \(.status)"'
  after=$(echo "$page" | jq -r '.next // empty')
  [ -z "$after" ] && break
done
```

## Quotas

Le quota est compté **par clé et par projet**, sur une fenêtre fixe d'une minute. Il est de 120 requêtes par minute au plus ; l'exploitant de l'instance peut l'abaisser avec `MVP_API_RATE_LIMIT_PER_MINUTE`, jamais le relever. Les appels à `GET /api/v1/projects` sont comptés pour la clé, hors projet.

Au-delà, la réponse est `429 rate_limited` avec l'en-tête `Retry-After`, en secondes, jusqu'à la fin de la minute en cours. Les requêtes refusées comptent aussi dans la fenêtre : attendez avant de réessayer.

Ce quota s'ajoute aux limites métier : plafonds de jetons, budgets et concurrence des exécutions. Voir [Budgets et plafonds](../05-rapports-usage-et-couts/04-budgets-et-plafonds.md).

> [!TIP]
> Pour suivre une exécution, interrogez son adresse toutes les 10 à 30 secondes. Un intervalle plus court consomme le quota du projet sans accélérer le traitement.

## Pour continuer

Interprétez chaque refus : [Erreurs](05-erreurs.md).
