Xử lý các lỗi API, giới hạn tỷ lệ và các lần thử lại của Notiondesk

API Notiondesk trả lời mọi lỗi bằng cùng một gói JSON và một tiêu đề code có thể đọc được bằng máy, giới hạn mỗi khóa ở mức 120 lần đọc và 20 lần ghi mỗi phút, và cho phép bạn thử lại bất kỳ thay đổi nào một cách an toàn với tiêu đề Idempotency-Key. Bài viết này liệt kê mọi mã lỗi của API Notiondesk, giải thích các giới hạn tốc độ và tiêu đề của chúng, và chỉ ra cách xây dựng các lần thử lại mà không bao giờ thay đổi bất cứ điều gì hai lần.

Phong bì lỗi API Notiondesk

Mọi lỗi đều có cùng hình dạng và mọi trường dữ liệu đều luôn hiện diện:

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

Cách field đặt tên cho một giá trị

• Tên của trường cấp cao nhất là: page_size.

• Một trường bên trong danh sách đặt tên cho danh sách, mục trong ngoặc, sau đó là tên trường: items[fr].page_title.

• Dấu ngoặc vuông chứa mã định danh của mục nhập như bạn đã gửi (locale trong items, category_id trong changelog_categories) khi mỗi mục nhập có một mã định danh riêng biệt. Nếu không, nó sẽ chứa vị trí dựa trên chỉ số 0 của mục nhập: items[0].locale.

• Có vấn đề với toàn bộ yêu cầu đã được "field": null khắc phục.

Mã lỗi API Notiondesk

Yêu cầu truy cập trung tâm trợ giúp hoặc tài nguyên bên ngoài không gian làm việc của bạn sẽ trả về mã lỗi 404 not_found, vì vậy API sẽ không bao giờ tiết lộ liệu nó có tồn tại hay không.

Giới hạn tốc độ API Notiondesk

Mỗi khóa API và mỗi lần cấp quyền OAuth đều có hai ngân sách yêu cầu, được tính toán trong khoảng thời gian một phút trượt:

Các báo cáo phân tích cũng được tính vào ngân sách 30 yêu cầu mỗi phút cho mỗi trung tâm trợ giúp , được chia sẻ bởi mọi khóa và ứng dụng OAuth của không gian làm việc.

Phản hồi có ba tiêu đề:

Yêu cầu về ngân sách trả lời 429 rate_limited. Chờ số giây trong Retry-After trước khi gửi yêu cầu tiếp theo.

Lưu ý: Giới hạn tỷ lệ được tính theo từng khóa hoặc từng cấp quyền OAuth, chứ không phải theo từng không gian làm việc. Hai tích hợp với các khóa riêng biệt không làm chậm lẫn nhau, ngoại trừ ngân sách phân tích dùng chung.

Thử lại một cách an toàn với Idempotency-Key

Lỗi hết thời gian chờ mạng khiến bạn không chắc chắn liệu thay đổi đã được thực hiện thành công hay chưa. Tiêu đề Idempotency-Key cho phép bạn gửi lại cùng một yêu cầu mà không cần thay đổi bất cứ điều gì hai lần.

Mọi tuyến đường thay đổi đều chấp nhận điều này: thay đổi chuyển hướng trang, cập nhật cài đặt và thương hiệu, thay đổi tích hợp và các trình kích hoạt đồng bộ hóa. Hãy gửi một giá trị duy nhất từ ​​1 đến 255 ký tự, chẳng hạn như UUID, trong lần thử đầu tiên và gửi cùng một giá trị đó trong mỗi lần thử lại:

Điều gì xảy ra khi thử lại:

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

Phản hồi thành công sẽ mang theo X-Idempotent-Replay: false lần đầu tiên và true khi phát lại. Notiondesk giữ khóa trong ít nhất 24 giờ. Khóa thuộc về khóa API hoặc cấp quyền OAuth đã gửi nó, và cấp quyền OAuth giữ nguyên khóa của nó ngay cả khi làm mới mã thông báo.

Nếu không có tiêu đề, yêu cầu chỉ được thực hiện một lần, và khi thử lại sẽ thực hiện lại lần nữa.

Một chiến lược thử lại hiệu quả

1. Tạo một Idempotency-Key cho mỗi thay đổi logic và sử dụng lại nó cho mỗi lần thử lại thay đổi đó.

2. Tại 429 rate_limited, chờ Retry-After giây, sau đó thử lại.

3. Trên 409 request_in_progress, hãy đợi vài giây, sau đó thử lại với cùng một phím. Trên 409 conflict_error, quá trình đồng bộ hóa trung tâm trợ giúp đang chạy: hãy đợi vài phút trước khi bạn kích hoạt lại, hoặc bỏ qua lần chạy này.

4. Trên 500 trở lên, hoặc khi xảy ra lỗi mạng, hãy thử lại với phương pháp lùi thời gian theo cấp số nhân, ví dụ sau 1, 2, 4 và 8 giây.

5. Không bao giờ thử lại 400, 401, 403, 404 hoặc 422 mà không thay đổi. Hãy sửa yêu cầu trước.

Trong JavaScript, đối với bất kỳ tuyến đường nào thay đổi một giá trị nào đó, nó sẽ dừng lại ở conflict_error và để lại quyết định đó cho mã của bạn:

Câu hỏi thường gặp

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

Tiếp theo là gì?

• Phân trang và phiên bản Notiondesk Yêu cầu API

• Xác thực với API Notiondesk bằng khóa API.

• Bắt đầu sử dụng API REST Notiondesk