Verwerk API-fouten, snelheidslimieten en herhaalpogingen voor Notiondesk.

De Notiondesk API beantwoordt elke fout met dezelfde JSON-envelop en een machineleesbare code, beperkt elke sleutel tot 120 lees- en 20 schrijfbewerkingen per minuut en stelt u in staat elke wijziging veilig opnieuw uit te voeren met een Idempotency-Key header. Dit artikel bevat een lijst van alle Notiondesk API-foutcodes, legt de snelheidslimieten en hun headers uit en laat zien hoe u herhaalpogingen kunt bouwen die nooit iets twee keer wijzigen.

De Notiondesk API-foutomhulsel

Elke foutmelding heeft dezelfde vorm en elk veld is altijd aanwezig:

{
  "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."}
  ]
}

Hoe field een waarde benoemt

• Een veld op het hoogste niveau is de naam: page_size.

• Een veld binnen een lijst geeft de naam van de lijst, het item tussen haakjes, en vervolgens het veld: items[fr].page_title.

• De haakjes bevatten de identificatiecode van de vermelding zoals u die hebt verzonden (de locale in items, de category_id in changelog_categories) wanneer elke vermelding een unieke identificatiecode heeft. Anders bevatten ze de nulgebaseerde positie van de vermelding: items[0].locale.

• Er is een probleem met het verzoek als geheel, "field": null.

Notiondesk API-foutcodes

Een verzoek om een ​​helpcentrum of bron buiten uw werkruimte resulteert in de foutmelding 404 not_found, waardoor de API nooit onthult of deze bestaat.

Notiondesk API-snelheidslimieten

Elke API-sleutel en elke OAuth-toekenning heeft twee aanvraagbudgetten, geteld over een verschuivend venster van één minuut:

Analyserapporten tellen ook mee voor een budget van 30 aanvragen per minuut per helpcentrum , dat wordt gedeeld door elke sleutel en OAuth-app in de werkruimte.

De antwoorden bevatten drie kopteksten:

Een verzoek over het budget beantwoordt met 429 rate_limited. Wacht het aantal seconden in Retry-After voordat u het volgende verzoek verzendt.

Let op: Snelheidslimieten worden per sleutel of per OAuth-toekenning geteld, niet per werkruimte. Twee integraties met afzonderlijke sleutels vertragen elkaar niet, behalve wat betreft het gedeelde analysebudget.

Probeer het opnieuw met Idempotency-Key

Een netwerktime-out geeft geen zekerheid of een wijziging is doorgevoerd. De header Idempotency-Key zorgt ervoor dat je hetzelfde verzoek opnieuw kunt verzenden zonder dat er twee keer iets wordt gewijzigd.

Elke route die iets wijzigt, accepteert die wijziging: wijzigingen in paginadirecties, updates van instellingen en branding, integratiewijzigingen en synchronisatietriggers. Stuur bij de eerste poging een unieke waarde van 1 tot 255 tekens, zoals een UUID, en dezelfde waarde bij elke nieuwe poging.

Wat gebeurt er bij een nieuwe poging?

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"}'

Een succesvolle reactie bevat de eerste keer X-Idempotent-Replay: false en bij een herhaling true. Notiondesk bewaart een sleutel minimaal 24 uur. Een sleutel behoort tot de API-sleutel of OAuth-grant die deze heeft verzonden, en een OAuth-grant bewaart zijn sleutels ook na het vernieuwen van tokens.

Zonder de header wordt een verzoek eenmaal uitgevoerd en een nieuwe poging nogmaals.

Een herhaalstrategie die werkt

1. Genereer één Idempotency-Key per logische wijziging en hergebruik deze voor elke herhaling van die wijziging.

2. Wacht bij 429 rate_limited Retry-After seconden en probeer het dan opnieuw.

3. Bij 409 request_in_progress, wacht een paar seconden en probeer het dan opnieuw met dezelfde sleutel. Bij 409 conflict_error is er al een synchronisatie van het helpcentrum bezig: wacht een paar minuten voordat u het opnieuw probeert, of sla deze synchronisatie over.

4. Bij 500 en hoger, of bij een netwerkfout, probeer het opnieuw met exponentiële backoff, bijvoorbeeld na 1, 2, 4 en 8 seconden.

5. Probeer 400, 401, 403, 404 of 422 nooit ongewijzigd opnieuw. Corrigeer eerst het verzoek.

In JavaScript geldt dit voor elke route die iets verandert. Het stopt bij conflict_error en laat die beslissing over aan je code:

Veelgestelde vragen

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`);
}

Wat volgt?

• Paginatie en versie Notiondesk API-verzoeken

• Authenticeer bij de Notiondesk API met behulp van API-sleutels.

• Ga aan de slag met de Notiondesk REST API