Gérer les erreurs, les limites de débit et les nouvelles tentatives de l'API Notiondesk

L'API Notiondesk renvoie chaque erreur avec la même enveloppe JSON et un en-tête code lisible par machine, limite chaque clé à 120 lectures et 20 écritures par minute, et permet de retenter toute modification en toute sécurité grâce à un en-tête Idempotency-Key. Cet article répertorie tous les codes d'erreur de l'API Notiondesk, explique les limites de débit et leurs en-têtes, et montre comment configurer des tentatives de reconnexion qui évitent de modifier deux fois la même donnée.

L'enveloppe d'erreur de l'API Notiondesk

Chaque erreur répond de la même manière, et chaque champ est toujours présent :

{
  "object": "error",
  "code": "validation_error",
  "message": "The request parameters are invalid.",
  "request_id": "0f2c1e94-7a1b-4c2d-9e3f-5a6b7c8d9e0f",
  "errors": [
    {"field": "page_size", "message": "This value should be between 1 and 100."}
  ]
}

Comment field nomme une valeur

• Un champ de niveau supérieur est son nom : page_size.

• Un champ à l'intérieur d'une liste nomme la liste, l'entrée entre crochets, puis le champ : items[fr].page_title.

• Le crochet contient l'identifiant de l'entrée tel que vous l'avez envoyé (locale dans items, category_id dans changelog_categories) lorsque chaque entrée possède un identifiant unique. Sinon, il contient la position de l'entrée (à partir de zéro) : items[0].locale.

• Un problème avec la requête dans son ensemble a été "field": null.

Notiondesk Codes d'erreur de l'API

Une demande pour un centre d'aide ou une ressource en dehors de votre espace de travail répond 404 not_found, l'API ne révèle donc jamais si elle existe.

Notiondesk Limites de débit de l'API

Chaque clé API et chaque autorisation OAuth dispose de deux budgets de requêtes, comptabilisés sur une fenêtre glissante d'une minute :

Les rapports analytiques sont également comptabilisés dans un budget de 30 requêtes par minute et par centre d'aide , partagé par chaque application clé et OAuth de l'espace de travail.

Les réponses comportent trois en-têtes :

Une requête dépassant le budget répond 429 rate_limited. Attendez le nombre de secondes indiqué dans Retry-After avant d'envoyer la requête suivante.

Remarque : Les limites de débit sont calculées par clé ou par autorisation OAuth, et non par espace de travail. Deux intégrations avec des clés distinctes ne se ralentissent pas mutuellement, sauf au niveau du budget d’analyse partagé.

Réessayez en toute sécurité avec Idempotency-Key

Un délai d'attente réseau vous empêche de savoir si une modification a bien été prise en compte. L'en-tête Idempotency-Key vous permet de renvoyer la même requête sans rien modifier deux fois.

Chaque route qui modifie un élément l'accepte : changements de redirection de page, mises à jour des paramètres et de l'identité visuelle, modifications d'intégration et déclencheurs de synchronisation. Envoyez une valeur unique de 1 à 255 caractères, comme un UUID, lors de la première tentative, puis la même valeur à chaque nouvelle tentative.

Que se passe-t-il lors d'une nouvelle tentative :

curl -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0d6b1e-create-getting-started" \
  -d '{"type": "article", "source_path": "/legacy/getting-started", "target_id": "1761580412", "locale": "en"}'

Une réponse réussie contient X-Idempotent-Replay: false lors de la première exécution et true lors d'une nouvelle exécution. Notiondesk conserve une clé pendant au moins 24 heures. Une clé est associée à la clé API ou à l'autorisation OAuth qui l'a envoyée, et une autorisation OAuth conserve ses clés lors des renouvellements de jeton.

Sans l'en-tête, une requête est exécutée une première fois, puis une nouvelle tentative est effectuée.

Une stratégie de nouvelle tentative qui fonctionne

1. Générez un Idempotency-Key par modification logique et réutilisez-le pour chaque nouvelle tentative de cette modification.

2. Sur 429 rate_limited, attendez Retry-After secondes, puis réessayez.

3. Sur 409 request_in_progress, patientez quelques secondes, puis réessayez avec la même touche. Sur 409 conflict_error, une synchronisation du centre d'aide est déjà en cours : patientez quelques minutes avant de réessayer, ou ignorez cette opération.

4. Sur 500 et supérieur, ou en cas d'erreur réseau, réessayer avec un délai exponentiel, par exemple après 1, 2, 4 et 8 secondes.

5. Ne réessayez jamais 400, 401, 403, 404 ou 422 sans les modifier. Corrigez d'abord la requête.

En JavaScript, pour toute route qui modifie un élément, le programme s'arrête sur conflict_error et laisse cette décision à votre code :

Questions fréquentes

import { randomUUID } from "node:crypto";

const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function notiondeskRequest(method, path, body, attempts = 5) {
  const idempotencyKey = randomUUID();

  for (let attempt = 0; attempt < attempts; attempt++) {
    let response;
    try {
      response = await fetch(`https://api.notiondesk.so${path}`, {
        method,
        headers: {
          Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
          "nd-version": "2026-10-16",
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        body: body ? JSON.stringify(body) : undefined,
      });
    } catch {
      await sleep(2 ** attempt);
      continue;
    }

    if (response.ok) {
      return response.status === 204 ? null : response.json();
    }

    const error = await response.json().catch(() => ({}));
    const retryable = response.status === 429 || response.status >= 500 || error.code === "request_in_progress";
    if (!retryable) {
      throw new Error(`${response.status} ${error.code}: ${error.message}`);
    }

    const retryAfter = Number(response.headers.get("Retry-After"));
    await sleep(retryAfter > 0 ? retryAfter : 2 ** attempt);
  }

  throw new Error(`Notiondesk request failed after ${attempts} attempts`);
}

Et ensuite ?

• Requêtes API de pagination et de version Notiondesk

• Authentifiez-vous auprès de l'API Notiondesk à l'aide de clés API.

• Commencez à utiliser l'API REST Notiondesk