Draftn.io docs · api
Fundamentos

Tratamento de erros

A API sinaliza falhas pelo código de status HTTP e, na maioria dos casos, por um corpo JSON com error e message. Sempre verifique o status antes de consumir o corpo.

Formato de erro

Quando há corpo, a estrutura é simples e consistente:

errorstring
Identificação curta do erro. Sempre presente nas respostas de erro com corpo.
messagestring
Descrição mais detalhada, quando disponível. Pode estar ausente em alguns erros.
erro 
{
  "error": "API Key inválida ou ausente",
  "message": "Forneça uma chave válida no header X-API-Key."
}

Erros por situação

StatusQuando ocorreO que fazer
400 Parâmetro inválido: format de anúncio desconhecido, corpo de slots inválido, q de busca com menos de 3 caracteres, ou clickToken ausente/expirado. Corrija a requisição. Não repita sem alterar a entrada.
401 Chave de API ausente ou inválida no header X-API-Key. Confira a variável de ambiente e, se preciso, rotacione a chave no painel.
403 No clique de anúncio, o Origin/Referer não corresponde ao domínio configurado do blog. Garanta que a chamada parta do domínio autorizado do blog.
404 Recurso não encontrado: post, categoria ou tag inexistente (ou não publicado) para o ID/slug informado. Valide o identificador; trate como "conteúdo indisponível".
409 No clique de anúncio, o clickToken já foi utilizado (uso único). Não reenvie o mesmo token; obtenha um novo na próxima entrega.

Um tratador reutilizável

Centralize a lógica de status e a leitura tolerante do corpo em uma função:

TypeScript 
interface ApiError { error: string; message?: string }

async function draftin<T>(path: string): Promise<T> {
  const res = await fetch("https://api.draftin.io" + path, {
    headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
  });

  if (res.ok) return res.json() as Promise<T>;

  // tenta extrair o corpo de erro — nem todo erro traz JSON
  let detalhe = res.statusText;
  try {
    const body = (await res.json()) as ApiError;
    detalhe = body.message ?? body.error ?? detalhe;
  } catch { /* corpo vazio ou não-JSON */ }

  switch (res.status) {
    case 400: throw new Error(`Requisição inválida: ${detalhe}`);
    case 401: throw new Error("Chave de API inválida ou ausente.");
    case 403: throw new Error("Origem não autorizada para este blog.");
    case 404: throw new Error("Recurso não encontrado.");
    case 409: throw new Error("Conflito: token já utilizado.");
    default:  throw new Error(`Erro ${res.status}: ${detalhe}`);
  }
}

Princípios

  • Status primeiro, corpo depois. Ramifique pelo código HTTP; use o corpo só para enriquecer a mensagem.
  • Leitura tolerante. Envolva res.json() em try/catch — o corpo pode estar vazio.
  • Não repita 4xx. Erros de cliente (400/401/403/404/409) não se resolvem com retentativa; corrija a entrada.
  • Repita 5xx com backoff. Erros de servidor são transitórios; veja Rate limits.