Обработка ошибок API Notiondesk, ограничений скорости и повторных попыток.

API Notiondesk обрабатывает каждую ошибку с помощью одного и того же JSON-конверта и машиночитаемого заголовка code, ограничивает количество операций чтения и записи для каждого ключа до 120 в минуту и ​​позволяет безопасно повторить любое изменение с помощью заголовка Idempotency-Key. В этой статье перечислены все коды ошибок API Notiondesk, объясняются ограничения скорости и их заголовки, а также показано, как создавать сценарии повторных попыток, которые никогда не изменят ничего дважды.

Ошибка 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.

Коды ошибок API Notiondesk

Запрос к справочному центру или ресурсу за пределами вашего рабочего пространства приводит к ошибке 404 not_found, поэтому API никогда не раскрывает информацию о его существовании.

Notiondesk Ограничения скорости API

Каждый API-ключ и каждое разрешение OAuth имеют два лимита запросов, отсчитываемых в течение скользящего минутного окна:

Аналитические отчеты также учитываются в рамках бюджета в 30 запросов в минуту на каждый центр поддержки , который распределяется между всеми приложениями Key и 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.

• Начните работу с REST API Notiondesk