Tratamento de erros

Formato de erro

A maioria dos erros de API retorna um objeto JSON com uma única string error:

{ "error": "Monitor not found" }

Alguns erros incluem campos adicionais:

Erros de limite de taxa (429) incluem um campo retry_after_seconds:

{
  "error": "Too many requests",
  "retry_after_seconds": 60
}

Erros de token OAuth seguem RFC 6749 e incluem um error_description:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Códigos de status HTTP

Estado	Significado
400	Solicitação incorreta — campos ausentes ou inválidos
401	Não autenticado – token ausente, inválido ou expirado
403	Proibido — token válido, mas permissões insuficientes ou limite do plano atingido
404	Recurso não encontrado
429	Taxa limitada – recue e tente novamente
500	Erro interno do servidor — transitório, tente novamente com espera
503	Serviço indisponível – dependência upstream (por exemplo, provedor OAuth) está inativa

Mensagens de erro comuns

Mensagem	Estado	O que aconteceu
"Authorization header missing or invalid"	401	Nenhum cabeçalho Authorization: Bearer <token>
"Invalid or expired token"	401	O token expirou ou foi adulterado — autenticar novamente
"Invalid API key"	401	A chave API usada para gerar este token foi revogada
"Monitor not found"	404	Não existe nenhum monitor com este ID em sua equipe
"Your plan allows a maximum of N monitors"	403	Atualize seu plano para criar mais monitores
"Too many requests"	429	Você excedeu o limite de taxa — veja o campo retry_after_seconds
"Internal server error"	500	Erro temporário do servidor – tente novamente com espera exponencial

Tratamento de erros no código

const res = await fetch('https://www.diffhook.com/api/monitors', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
})

if (!res.ok) {
  const body = await res.json()
  const message = body.error

  if (res.status === 429) {
    const retryAfter = body.retry_after_seconds ?? 60
    // wait and retry
  } else if (res.status === 401) {
    // re-authenticate with POST /api/oauth/token
  } else {
    console.error(message)
  }
}

Erros 5xx

Os erros do servidor são temporários. Tente novamente com espera exponencial – a maioria resolve em segundos. Se um 500 ou 503 persistir por mais de alguns minutos, verifique nossa página de status ou envie um e-mail para support@diffhook.com.