Manejo de errores

Formato de error

La mayoría de los errores de API devuelven un objeto JSON con una única cadena error. Esta referencia cubre códigos HTTP, mensajes de validación, guía de reintentos y manejo de fallos en handlers de webhook.

{ "error": "Monitor not found" }

Algunos errores incluyen campos adicionales:

Errores de límite de tasa (429) incluyen un campo retry_after_seconds:

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

Errores de token de OAuth siguen a RFC 6749 e incluyen un error_description:

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

Códigos de estado HTTP

Estado	Significado
400	Solicitud incorrecta: campos faltantes o no válidos
401	Sin autenticar: token faltante, no válido o caducado
403	Prohibido: token válido pero permisos insuficientes o se alcanzó el límite del plan
404	Recurso no encontrado
429	Tarifa limitada: retroceda y vuelva a intentarlo
500	Error interno del servidor: transitorio, reinténtelo con retroceso
503	Servicio no disponible: la dependencia ascendente (por ejemplo, el proveedor de OAuth) está inactiva

Mensajes de error comunes

Mensaje	Estado	¿Qué pasó?
"Authorization header missing or invalid"	401	Sin encabezado Authorization: Bearer <token>
"Invalid or expired token"	401	El token ha caducado o ha sido manipulado: volver a autenticarse
"Invalid API key"	401	La clave API utilizada para generar este token ha sido revocada
"Monitor not found"	404	No existe ningún monitor con este ID en su equipo
"Your plan allows a maximum of N monitors"	403	Actualice su plan para crear más monitores
"Too many requests"	429	Ha excedido el límite de tasa; consulte el campo retry_after_seconds
"Internal server error"	500	Error transitorio del servidor: vuelva a intentarlo con retroceso exponencial

Manejo de errores en el 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)
  }
}

errores 5xx

Los errores del servidor son transitorios. Vuelva a intentarlo con un retroceso exponencial; la mayoría se resuelve en segundos. Si un 500 o 503 persiste durante más de unos minutos, consulte nuestra página de estado o envíe un correo electrónico a support@diffhook.com.