Gestione degli errori

Formato errore

La maggior parte degli errori API restituisce un oggetto JSON con una singola stringa error. Questo riferimento copre codici HTTP, messaggi di validazione, retry e gestione degli errori negli handler webhook.

{ "error": "Monitor not found" }

Alcuni errori includono campi aggiuntivi:

Errori di limite di velocità (429) includono un campo retry_after_seconds:

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

Errori token OAuth seguono RFC 6749 e includono error_description:

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

Codici di stato HTTP

Stato	Significato
400	Richiesta errata: campi mancanti o non validi
401	Non autenticato: token mancante, non valido o scaduto
403	Vietato: token valido ma autorizzazioni insufficienti o limite del piano raggiunto
404	Risorsa non trovata
429	Tariffa limitata: fai marcia indietro e riprova
500	Errore interno del server: temporaneo, riprova con backoff
503	Servizio non disponibile: la dipendenza upstream (ad esempio il provider OAuth) è inattiva

Messaggi di errore comuni

Messaggio	Stato	Cosa è successo
"Authorization header missing or invalid"	401	Nessuna intestazione Authorization: Bearer <token>
"Invalid or expired token"	401	Il token è scaduto o è stato manomesso: autenticarsi nuovamente
"Invalid API key"	401	La chiave API utilizzata per generare questo token è stata revocata
"Monitor not found"	404	Nel tuo team non esiste alcun monitor con questo ID
"Your plan allows a maximum of N monitors"	403	Aggiorna il tuo piano per creare più monitor
"Too many requests"	429	Hai superato il limite di tariffa: consulta il campo retry_after_seconds
"Internal server error"	500	Errore temporaneo del server: riprova con backoff esponenziale

Gestione degli errori nel codice

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

Errori 5xx

Gli errori del server sono temporanei. Riprova con un backoff esponenziale: la maggior parte si risolve in pochi secondi. Se un 500 o 503 persiste per più di qualche minuto, controlla la nostra pagina di stato o invia un'e-mail a support@diffhook.com.