טיפול בשגיאות API, מגבלות קצב וניסיונות חוזרים של Notiondesk

ממשק ה-API Notiondesk עונה על כל שגיאה עם אותה מעטפת JSON וקובץ code הניתן לקריאה על ידי מכונה, מגביל כל מפתח ל-120 קריאות ו-20 כתיבות לדקה, ומאפשר לך לנסות שוב כל שינוי בבטחה עם כותרת Idempotency-Key. מאמר זה מפרט כל קוד שגיאה של Notiondesk ב-API, מסביר את מגבלות הקצב ואת הכותרות שלהן, ומראה כיצד לבנות ניסיונות חוזרים שלא ישנו דבר פעמיים.

מעטפת השגיאה של ה-API Notiondesk

כל שגיאה עונה על אותה צורה, וכל שדה תמיד קיים:

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

כיצד field נותן שם לערך

• שדה ברמה העליונה הוא שמו: page_size.

• שדה בתוך רשימה נותן את השם לרשימה, לערך שבסוגריים, ולאחר מכן לשדה: items[fr].page_title.

• הסוגריים מכילים את מזהה הערך כפי ששלחת אותו (locale ב-items, category_id ב-changelog_categories) כאשר לכל ערך יש מזהה ייחודי. אחרת, הוא מכיל את מיקום האפס של הערך: items[0].locale.

• בעיה בבקשה בכללותה כוללת את "field": null.

קודי שגיאה של Notiondesk ב-API

בקשה למרכז עזרה או משאב מחוץ לסביבת העבודה שלך עונה על שאלה 404 not_found, כך שה-API לעולם לא חושף אם הוא קיים.

מגבלות קצב של API Notiondesk

לכל מפתח API ולכל מענק OAuth יש שני תקציבי בקשה, הנספרים על פני חלון הזזה של דקה אחת:

דוחות אנליטיקס נחשבים גם כחלק מתקציב של 30 בקשות לדקה לכל מרכז עזרה , המשותף לכל מפתח ואפליקציית OAuth בסביבת העבודה.

לתגובות יש שלוש כותרות:

בקשה חורגת מהתקציב עונה על 429 rate_limited. המתן את מספר השניות ב-Retry-After לפני שליחת הבקשה הבאה.

הערה: מגבלות התעריפים נספרות לפי מפתח או לפי מתן OAuth, ולא לפי סביבת עבודה. שתי אינטגרציות עם מפתחות נפרדים אינן מאטות זו את זו, למעט בתקציב האנליטיקה המשותף.

נסה שוב בבטחה עם Idempotency-Key

פסק זמן ברשת משאיר אותך לא בטוח האם שינוי התבצע. כותרת Idempotency-Key מאפשרת לך לשלוח את אותה בקשה שוב מבלי לשנות דבר פעמיים.

כל נתיב שמשנה משהו מקבל זאת: שינויים בהפניה מחדש של דף, עדכוני הגדרות ומיתוג, שינויי אינטגרציה וטריגרים של סנכרון. שלח ערך ייחודי של 1 עד 255 תווים, כגון UUID, בניסיון הראשון, ואת אותו ערך בכל ניסיון חוזר:

מה קורה בניסיון חוזר:

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

תגובה מוצלחת נושאת את X-Idempotent-Replay: false בפעם הראשונה ואת true בהשמעה חוזרת. Notiondesk שומר מפתח למשך 24 שעות לפחות. מפתח שייך למפתח ה-API או להענקת OAuth ששלחו אותו, והענקת OAuth שומרת את המפתחות שלו לאורך רענון האסימון.

ללא הכותרת, בקשה רצה פעם אחת, וניסיון חוזר רצה שוב.

אסטרטגיית ניסיון חוזר שעובדת

1. צור Idempotency-Key אחד לכל שינוי לוגי, והשתמש בו שוב עבור כל ניסיון חוזר של שינוי זה.

2. ב-429 rate_limited, המתן Retry-After שניות, ולאחר מכן נסה שוב.

3. ב-409 request_in_progress, המתן מספר שניות, ולאחר מכן נסה שוב עם אותו מקש. ב-409 conflict_error, סנכרון של מרכז העזרה כבר פועל: המתן מספר דקות לפני שתפעיל שוב, או דלג על הפעלה זו.

4. ב-500 ומעלה, או לאחר שגיאת רשת, יש לנסות שוב עם אפשרות ביטול פעולות אקספוננציאליות, לדוגמה לאחר 1, 2, 4 ו-8 שניות.

5. לעולם אל תנסה שוב את 400, 401, 403, 404 או 422 ללא שינוי. תקן תחילה את הבקשה.

ב-JavaScript, עבור כל מסלול שמשנה משהו. הוא עוצר ב-conflict_error ומשאיר את ההחלטה הזו לקוד שלך:

שאלות נפוצות

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

מה הלאה

• בקשות API לעמודים וגירסה Notiondesk

• אימות באמצעות ממשק ה-API Notiondesk באמצעות מפתחות API

• התחל עם ממשק ה-API של REST Notiondesk