Gestire gli errori dell'API Notiondesk, i limiti di frequenza e i tentativi di ripetizione.

L'API Notiondesk risponde a ogni errore con la stessa busta JSON e un'intestazione code leggibile dalla macchina, limita ogni chiave a 120 letture e 20 scritture al minuto e consente di riprovare qualsiasi modifica in modo sicuro con un'intestazione Idempotency-Key. Questo articolo elenca tutti i codici di errore dell'API Notiondesk, spiega i limiti di frequenza e le relative intestazioni e mostra come creare tentativi di ripetizione che non modifichino mai nulla due volte.

L'involucro di errore dell'API Notiondesk

Ogni errore risponde alla stessa forma e ogni campo è sempre presente:

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

Come field nomina un valore

• Il nome del campo di primo livello è: page_size.

• Un campo all'interno di un elenco specifica il nome dell'elenco, la voce tra parentesi quadre e quindi il nome del campo: items[fr].page_title.

• La parentesi quadre contiene l'identificativo della voce così come è stato inviato (il locale in items, il category_id in changelog_categories) quando ogni voce ha un identificativo univoco. Altrimenti contiene la posizione della voce a base zero: items[0].locale.

• Si è verificato un problema con la richiesta nel suo complesso "field": null.

Notiondesk Codici di errore API

Una richiesta di centro assistenza o di una risorsa esterna al tuo spazio di lavoro risponde con il codice 404 not_found, quindi l'API non rivela mai se esiste.

Notiondesk Limiti di frequenza API

Ogni chiave API e ogni concessione OAuth dispone di due budget di richieste, conteggiati su una finestra temporale scorrevole di un minuto:

I report analitici vengono inoltre conteggiati in base a un budget di 30 richieste al minuto per ogni centro assistenza , condiviso da ogni chiave e app OAuth dell'area di lavoro.

Le risposte contengono tre intestazioni:

Una richiesta che supera il budget risponde 429 rate_limited. Attendi il numero di secondi in Retry-After prima di inviare la richiesta successiva.

Nota: i limiti di frequenza vengono conteggiati per chiave o per concessione OAuth, non per spazio di lavoro. Due integrazioni con chiavi separate non si rallentano a vicenda, tranne che per il budget di analisi condiviso.

Riprova in sicurezza con Idempotency-Key

Un timeout di rete non consente di avere la certezza che una modifica sia andata a buon fine. L'intestazione Idempotency-Key permette di inviare nuovamente la stessa richiesta senza apportare due volte le stesse modifiche.

Ogni percorso che apporta modifiche lo accetta: modifiche al reindirizzamento di pagina, aggiornamenti di impostazioni e branding, modifiche di integrazione e trigger di sincronizzazione. Invia un valore univoco da 1 a 255 caratteri, come un UUID, al primo tentativo e lo stesso valore a ogni tentativo successivo:

Cosa succede se si riprova:

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

Una risposta positiva contiene X-Idempotent-Replay: false la prima volta e true in caso di ripetizione. Notiondesk conserva una chiave per almeno 24 ore. Una chiave appartiene alla chiave API o alla concessione OAuth che l'ha inviata e una concessione OAuth conserva le sue chiavi anche dopo l'aggiornamento del token.

Senza l'intestazione, una richiesta viene eseguita una sola volta e un eventuale tentativo di ripetizione viene eseguito nuovamente.

Una strategia di riprova che funziona

1. Genera un oggetto Idempotency-Key per ogni modifica logica e riutilizzalo per ogni tentativo di ripetere tale modifica.

2. Il 429 rate_limited, attendi Retry-After secondi, quindi riprova.

3. Il giorno 409 request_in_progress, attendi qualche secondo, quindi riprova con lo stesso tasto. Il giorno 409 conflict_error è già in corso una sincronizzazione del centro assistenza: attendi qualche minuto prima di riprovare oppure salta questa esecuzione.

4. Su 500 e versioni successive, o in caso di errore di rete, riprova con un intervallo di tempo esponenziale, ad esempio dopo 1, 2, 4 e 8 secondi.

5. Non riprovare mai 400, 401, 403, 404 o 422 senza modifiche. Correggi prima la richiesta.

In JavaScript, per qualsiasi percorso che modifichi qualcosa, si ferma su conflict_error e lascia quella decisione al tuo codice:

Domande frequenti

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

Cosa succederà dopo?

• Richieste API di impaginazione e versione Notiondesk

• Autenticarsi con l'API Notiondesk utilizzando le chiavi API

• Inizia a utilizzare l'API REST Notiondesk