Docs / Erreurs et limites

Erreurs, idempotence et limites

Codes d’erreur de l’API nouko, idempotence avec Idempotency-Key et limite de 120 requêtes par minute.

Toutes les erreurs ont le même format :

HTTP/1.1 400 Bad Request
X-Request-Id: 9a7c…

{ "error": { "code": "invalid_request", "message": "country: Invalid enum value" } }

HTTP	Code	Cause	Que faire
400	`invalid_request`	Champ manquant ou invalide (détail dans `message`)	Corrigez la requête, ne réessayez pas telle quelle
400	`idempotency_key_required`	En-tête `Idempotency-Key` absent ou trop long	Ajoutez une clé stable de 120 caractères max.
401	`unauthorized`	Clé absente, invalide ou révoquée	Vérifiez la clé et son environnement
403	`account_suspended`	Compte suspendu par nouko	Contactez le support
404	`not_found`	Session inexistante ou d’un autre environnement	Vérifiez l’id et la clé utilisée
409	`not_cancellable`	Session déjà soumise ou terminée	Lisez son statut
429	`rate_limited`	Plus de 120 requêtes par minute	Attendez puis réessayez avec un délai croissant
500	`internal_error`	Erreur de nouko	Réessayez avec la même `Idempotency-Key`

Idempotence

Utilisez une clé liée à votre objet métier (ex. commande-001) et stockez-la. En cas de coupure réseau ou d’erreur 5xx, renvoyez exactement la même requête avec la même clé : vous obtenez la session existante, jamais un doublon.

// Même Idempotency-Key à chaque tentative : jamais de doublon
async function createWithRetry(payload, key, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    try {
      const res = await fetch('https://nouko.openclouds.fr/api/public/v1/sessions', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.NOUKO_API_KEY}`,
          'Idempotency-Key': key,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });
      if (res.status !== 429 && res.status < 500) return res.json(); // 200 si rejeu
    } catch { /* réseau : on réessaie */ }
    await new Promise(r => setTimeout(r, 2 ** i * 1000));
  }
  throw new Error('Nouko indisponible');
}

Limites

Limite	Valeur
Requêtes	120 par minute et par clé
Page de liste	100 sessions max.
Métadonnées	20 clés max.
Validité d’un lien	15 minutes à 30 jours
Réponse webhook attendue	moins de 8 secondes