Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób

Interfejs API Notiondesk odpowiada na każdy błąd za pomocą tej samej koperty JSON i maszynowo czytelnego code, ogranicza liczbę odczytów i zapisów dla każdego klucza do 120 na minutę oraz pozwala na bezpieczne ponawianie prób wprowadzenia dowolnej zmiany za pomocą nagłówka Idempotency-Key. W tym artykule wymieniono wszystkie kody błędów interfejsu API Notiondesk, wyjaśniono limity częstotliwości i ich nagłówki oraz pokazano, jak tworzyć ponawianie prób, które nigdy nie zmieniają niczego dwa razy.

Obwiednia błędów interfejsu API Notiondesk

Każdy błąd odpowiada temu samemu kształtowi i każde pole jest zawsze obecne:

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

Jak field nadaje nazwę wartości

• Pole najwyższego poziomu to jego nazwa: page_size.

• Pole wewnątrz listy zawiera nazwę listy, wpis w nawiasach, a następnie pole: items[fr].page_title.

• Nawias przechowuje identyfikator wpisu, jaki został przez Ciebie wysłany (locale w items, category_id w changelog_categories), gdy każdy wpis ma odrębny identyfikator. W przeciwnym razie przechowuje pozycję wpisu (licząc od zera): items[0].locale.

• Problem z całym żądaniem ma numer "field": null.

Notiondesk Kody błędów API

Prośba o dostęp do centrum pomocy lub zasobu spoza obszaru roboczego odpowiada na błąd 404 not_found, więc API nigdy nie ujawnia, czy takie centrum pomocy lub zasób istnieje.

Notiondesk Limity szybkości API

Każdy klucz API i każde przyznanie OAuth ma dwa budżety żądań, liczone w przesuwającym się oknie minutowym:

Raporty analityczne są również uwzględniane w budżecie 30 żądań na minutę na centrum pomocy , współdzielonych przez każdy klucz i aplikację OAuth w obszarze roboczym.

Odpowiedzi zawierają trzy nagłówki:

Żądanie przekraczające budżet odpowiada 429 rate_limited. Przed wysłaniem kolejnego żądania należy odczekać liczbę sekund równą liczbie Retry-After.

Uwaga: limity szybkości są naliczane dla każdego klucza lub uprawnienia OAuth, a nie dla każdego obszaru roboczego. Dwie integracje z oddzielnymi kluczami nie spowalniają się wzajemnie, z wyjątkiem wspólnego budżetu analitycznego.

Spróbuj ponownie bezpiecznie z Idempotency-Key

Przekroczenie limitu czasu sieci nie daje pewności, czy zmiana została wprowadzona. Nagłówek Idempotency-Key pozwala na ponowne wysłanie tego samego żądania bez konieczności dwukrotnej zmiany.

Każda trasa, która coś zmienia, akceptuje to: zmiany przekierowań stron, aktualizacje ustawień i brandingu, zmiany integracji i wyzwalacze synchronizacji. Wyślij unikalną wartość od 1 do 255 znaków, taką jak UUID, przy pierwszej próbie i tę samą wartość przy każdej kolejnej próbie:

Co się dzieje przy ponownej próbie:

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

Pomyślna odpowiedź niesie ze sobą X-Idempotent-Replay: false przy pierwszym odtworzeniu i true przy ponownym odtworzeniu. Notiondesk przechowuje klucz przez co najmniej 24 godziny. Klucz należy do klucza API lub autoryzacji OAuth, która go wysłała, a autoryzacja OAuth przechowuje swoje klucze po odświeżeniu tokena.

Bez nagłówka żądanie jest uruchamiane raz, po czym następuje ponowna próba.

Strategia ponawiania prób, która działa

1. Wygeneruj jeden Idempotency-Key na każdą zmianę logiczną i wykorzystuj go ponownie przy każdej próbie wprowadzenia tej zmiany.

2. W dniu 429 rate_limited odczekaj Retry-After sekund, a następnie spróbuj ponownie.

3. W dniu 409 request_in_progress odczekaj kilka sekund, a następnie spróbuj ponownie z tym samym kluczem. W dniu 409 conflict_error synchronizacja centrum pomocy jest już uruchomiona: odczekaj kilka minut przed ponownym uruchomieniem lub pomiń to uruchomienie.

4. W przypadku wersji 500 i nowszych lub w przypadku błędu sieciowego należy ponowić próbę z wykładniczym opóźnieniem, np. po 1, 2, 4 i 8 sekundach.

5. Nigdy nie próbuj ponownie użyć 400, 401, 403, 404 lub 422 bez zmian. Najpierw popraw żądanie.

W JavaScript, dla każdej trasy, która coś zmienia, zatrzymuje się na conflict_error i pozostawia decyzję Twojemu kodowi:

Często zadawane pytania

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

Co dalej?

• Paginacja i wersja Notiondesk żądań API

• Uwierzytelnij się za pomocą interfejsu API Notiondesk, używając kluczy API

• Rozpocznij korzystanie z interfejsu API REST Notiondesk