Lidar com erros da API Notiondesk, limites de taxa e novas tentativas.

A API Notiondesk responde a todos os erros com o mesmo envelope JSON e um cabeçalho code legível por máquina, limita cada chave a 120 leituras e 20 gravações por minuto e permite que você tente novamente qualquer alteração com segurança usando um cabeçalho Idempotency-Key. Este artigo lista todos os códigos de erro da API Notiondesk, explica os limites de taxa e seus respectivos cabeçalhos e mostra como criar novas tentativas que nunca alterem nada duas vezes.

O envelope de erro da API Notiondesk

Todas as respostas de erro têm o mesmo formato e todos os campos estão sempre presentes:

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

Como field nomeia um valor

• Um campo de nível superior é o seu nome: page_size.

• Um campo dentro de uma lista nomeia a lista, a entrada entre colchetes e, em seguida, o campo: items[fr].page_title.

• O colchete armazena o identificador da entrada conforme você o enviou (o locale em items, o category_id em changelog_categories) quando cada entrada possui um identificador distinto. Caso contrário, ele armazena a posição da entrada, baseada em zero: items[0].locale.

• Um problema com a solicitação como um todo foi "field": null.

Códigos de erro da API Notiondesk

Uma solicitação de um centro de ajuda ou recurso fora do seu espaço de trabalho retorna 404 not_found, portanto a API nunca revela se ele existe.

Notiondesk limites de taxa da API

Cada chave de API e cada concessão OAuth possui dois orçamentos de requisição, contabilizados em uma janela deslizante de um minuto:

Os relatórios analíticos também são contabilizados em um orçamento de 30 solicitações por minuto por central de ajuda , compartilhado por todas as chaves e aplicativos OAuth do espaço de trabalho.

As respostas contêm três cabeçalhos:

Uma solicitação acima do orçamento responde 429 rate_limited. Aguarde o número de segundos em Retry-After antes de enviar a próxima solicitação.

Observação: os limites de taxa são contabilizados por chave ou por concessão OAuth, não por espaço de trabalho. Duas integrações com chaves separadas não afetam o desempenho uma da outra, exceto no orçamento de análise compartilhado.

Tente novamente com segurança com Idempotency-Key

Um tempo limite de rede deixa você na dúvida se uma alteração foi efetivada. O cabeçalho Idempotency-Key permite que você envie a mesma solicitação novamente sem precisar alterar nada duas vezes.

Cada rota que altera algo aceita a mudança: alterações de redirecionamento de página, atualizações de configurações e identidade visual, alterações de integração e gatilhos de sincronização. Envie um valor exclusivo de 1 a 255 caracteres, como um UUID, na primeira tentativa e o mesmo valor em todas as tentativas subsequentes.

O que acontece em uma nova tentativa:

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

Uma resposta bem-sucedida carrega X-Idempotent-Replay: false na primeira vez e true em uma repetição. Notiondesk mantém uma chave por pelo menos 24 horas. Uma chave pertence à chave de API ou à concessão OAuth que a enviou, e uma concessão OAuth mantém suas chaves mesmo após a atualização do token.

Sem o cabeçalho, a solicitação é executada uma vez e, em caso de nova tentativa, é executada novamente.

Uma estratégia de repetição que funciona

1. Gere um Idempotency-Key por alteração lógica e reutilize-o para cada nova tentativa dessa alteração.

2. Em 429 rate_limited, aguarde Retry-After segundos e tente novamente.

3. Em 409 request_in_progress, aguarde alguns segundos e tente novamente com a mesma chave. Em 409 conflict_error, uma sincronização da central de ajuda já está em andamento: aguarde alguns minutos antes de tentar novamente ou ignore esta execução.

4. Em versões 500 e superiores, ou em caso de erro de rede, tente novamente com recuo exponencial, por exemplo, após 1, 2, 4 e 8 segundos.

5. Nunca tente novamente 400, 401, 403, 404 ou 422 sem alterações. Corrija a solicitação primeiro.

Em JavaScript, para qualquer rota que altere algo, o código para em conflict_error e deixa essa decisão para o seu código:

Perguntas frequentes

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

O que vem a seguir?

• Paginar e versão Notiondesk solicitações de API

• Autentique-se com a API Notiondesk usando chaves de API.

• Comece a usar a API REST Notiondesk