Gestionar errores de la API Notiondesk, límites de velocidad y reintentos.

La API Notiondesk responde a cada error con el mismo sobre JSON y un encabezado code legible por máquina, limita cada clave a 120 lecturas y 20 escrituras por minuto, y permite reintentar cualquier cambio de forma segura con un encabezado Idempotency-Key. Este artículo enumera todos los códigos de error de la API Notiondesk, explica los límites de velocidad y sus encabezados, y muestra cómo configurar reintentos que nunca realicen cambios dos veces.

El sobre de error de la API Notiondesk

Cada error responde con la misma forma, y ​​cada campo siempre está 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."}
  ]
}

Cómo field nombra un valor

• Un campo de nivel superior es su nombre: page_size.

• Un campo dentro de una lista nombra la lista, la entrada entre corchetes y luego el campo: items[fr].page_title.

• El corchete contiene el identificador de la entrada tal como lo enviaste (el locale en items, el category_id en changelog_categories) cuando cada entrada tiene uno distinto. De lo contrario, contiene la posición de la entrada basada en cero: items[0].locale.

• Se ha detectado un problema con la solicitud en su conjunto ("field": null).

Códigos de error de la API Notiondesk

Una solicitud de un centro de ayuda o recurso fuera de su espacio de trabajo devuelve el error 404 not_found, por lo que la API nunca revela si existe.

Límites de velocidad de la API

Cada clave API y cada concesión OAuth tiene dos presupuestos de solicitud, contabilizados en una ventana deslizante de un minuto:

Los informes analíticos también se contabilizan dentro de un presupuesto de 30 solicitudes por minuto por centro de ayuda , compartido por cada aplicación clave y OAuth del espacio de trabajo.

Las respuestas llevan tres encabezados:

Una solicitud que excede el presupuesto responde 429 rate_limited. Espere el número de segundos en Retry-After antes de enviar la siguiente solicitud.

Nota: Los límites de velocidad se contabilizan por clave o por concesión de OAuth, no por espacio de trabajo. Dos integraciones con claves independientes no se ralentizan entre sí, excepto en lo que respecta al presupuesto de análisis compartido.

Inténtalo de nuevo de forma segura con Idempotency-Key

Un tiempo de espera de red deja la duda de si se realizó un cambio. El encabezado Idempotency-Key permite enviar la misma solicitud nuevamente sin modificar nada dos veces.

Cada ruta que modifica algo lo acepta: cambios de redireccionamiento de página, actualizaciones de configuración y marca, cambios de integración y activadores de sincronización. Envíe un valor único de 1 a 255 caracteres, como un UUID, en el primer intento, y el mismo valor en cada reintento:

¿Qué sucede al reintentarlo?

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 respuesta exitosa incluye X-Idempotent-Replay: false la primera vez y true en una respuesta posterior. Notiondesk conserva una clave durante al menos 24 horas. Una clave pertenece a la clave API o concesión OAuth que la envió, y una concesión OAuth conserva sus claves entre actualizaciones de tokens.

Sin la cabecera, una solicitud se ejecuta una vez y un reintento se ejecuta de nuevo.

Una estrategia de reintento que funciona

1. Genera un Idempotency-Key por cada cambio lógico y reutilízalo para cada reintento de ese cambio.

2. En 429 rate_limited, espere Retry-After segundos y vuelva a intentarlo.

3. En 409 request_in_progress, espere unos segundos y vuelva a intentarlo con la misma clave. En 409 conflict_error, ya se está ejecutando una sincronización del centro de ayuda: espere unos minutos antes de volver a intentarlo o omita esta ejecución.

4. En caso de 500 o superior, o un error de red, reintente con retroceso exponencial, por ejemplo, después de 1, 2, 4 y 8 segundos.

5. Nunca vuelva a intentar 400, 401, 403, 404 o 422 sin cambios. Corrija la solicitud primero.

En JavaScript, para cualquier ruta que cambie algo, se detiene en conflict_error y deja esa decisión a tu código:

Preguntas frecuentes

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

¿Qué sigue?

• Solicitudes de API de paginación y versión Notiondesk

• Autentícate con la API Notiondesk usando claves de API.

• Comience a usar la API REST Notiondesk