Códigos de erro e resposta

A API Discuse sinaliza problemas de duas formas: um status de erro HTTP com uma message, ou uma resposta normal 200 cujos campos informam o que aconteceu. Esta página lista todos os casos para que você possa tratá-los corretamente — e explica aquele que costuma confundir: o esgotamento da cota de faturamento não é um erro HTTP.

Quais status HTTP a API retorna?

Leia a message em qualquer resposta que não seja 2xx. Falhas de autenticação retornam 401, falhas de limite de taxa retornam 429 e falhas de validação da solicitação retornam 400; trate 5xx como transitório e tente novamente com backoff.

Por que "cota esgotada" é 200, e não um erro?

Quando um projeto esgota sua franquia mensal de solicitações à API, POST /api/v2/check ainda retorna 200 — com o conteúdo tratado como sem violações, uma message explicando que a cota está esgotada e um objeto usage mostrando zero restante:

{
  "has_violations": false,
  "message": "API quota exceeded. Current: 10000, Limit: 10000",
  "usage": {
    "api_requests_used": 10000,
    "api_requests_limit": 10000,
    "api_requests_remaining": 0
  }
}

Isso é intencional: o fim da cota não deve parecer uma falha do servidor nem bloquear seu pipeline com uma exceção. Verifique usage.api_requests_remaining (e a message) em vez de confiar no código de status. Se você liberar o fluxo com base em um 200, uma cota esgotada deixaria conteúdo passar silenciosamente sem verificação — portanto, crie ramificações explicitamente com base nesses campos.

Como devo ler uma resposta bem-sucedida?

Um 200 de /api/v2/check sempre traz has_violations e cached; o restante é opcional:

Use has_violations para decidir o veredito geral e, em seguida, aprofunde-se em results.<check>.hit para saber qual verificação foi acionada.

Como o cache afeta as respostas?

Solicitações idênticas para o mesmo projeto são desduplicadas: uma repetição retorna cached: true com o mesmo resultado. O cache é por projeto. Observe que uma solicitação em cache ainda conta para sua cota de solicitações à API — ele economiza tempo de processamento, não cota.

Você pode anexar um request_id a uma solicitação para sua própria correlação; ele é devolvido na resposta.

Um cliente mínimo e correto

async function check(content, settings) {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.DISCUSE_API_KEY
    },
    body: JSON.stringify({ content, settings })
  });

  // 400: bad request — fix it, don't retry. 5xx: transient/auth/rate-limit — retry with backoff.
  if (response.status === 400) {
    throw new Error('Invalid request: ' + (await response.text()));
  }
  if (!response.ok) {
    throw new Error(`Discuse error ${response.status}`); // retry upstream with backoff
  }

  const data = await response.json();

  // Quota exhausted is a 200 — never treat it as "checked and clean".
  if (data.usage && data.usage.api_requests_remaining === 0 && data.message) {
    throw new Error('Quota exhausted: ' + data.message);
  }

  return data; // inspect data.has_violations and data.results
}

Relacionados

• Autenticação e chaves de API — chaves, o cabeçalho X-API-Key e limites de taxa
• Guia de início rápido — sua primeira solicitação em poucos minutos
• Análise de texto — o objeto results em detalhes