API Reference›Error Handling

Error Handling

All errors follow a consistent format with a machine-readable code and a human-readable message.

Error format

{
  "error": {
    "code": "MONITOR_LIMIT",
    "message": "Free tier is limited to 5 monitors"
  }
}

Error codes

Code	HTTP	Description
`UNAUTHORIZED`	401	Missing or invalid `Authorization` header
`INVALID_API_KEY`	401	API key is invalid or has been revoked
`FORBIDDEN`	403	Insufficient permissions for this action
`MONITOR_LIMIT`	403	Free tier monitor limit (5) reached
`NOT_FOUND`	404	Resource not found
`MISSING_FIELDS`	400	One or more required fields are missing
`INVALID_URL`	400	The provided URL is not reachable or invalid
`INVALID_INTERVAL`	400	Interval must be 5, 15, 30, 60, 360, or 1440
`RATE_LIMITED`	429	Too many requests — slow down
`SERVER_ERROR`	500	Internal error — contact support

Handling errors in code

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

if (!res.ok) {
  const { error } = await res.json()
  switch (error.code) {
    case 'MONITOR_LIMIT':
      // Prompt user to upgrade
      break
    case 'UNAUTHORIZED':
      // Redirect to login / prompt for new key
      break
    case 'RATE_LIMITED':
      // Back off and retry
      break
    default:
      // Log and surface to user
      console.error(error.message)
  }
}

5xx errors

Server errors (500, 502, 503) are transient. Retry with exponential backoff. If they persist for more than a few minutes, check our status page or contact support.