Errors

Failed requests return a JSON object with error and message. HTTP status codes match the failure class. HTTP 429 responses may also include rate_limit with the current window state. Treat the error value as the stable machine-readable code.

Error response

Fields

error Machine-readable error code.
message Human-readable explanation.
rate_limit Optional. Present on HTTP 429.

rate_limit

tier Rate tier this endpoint counts against (1-5).
cost Units consumed by this request against the tier window.
timeframe Rolling limit window: second, minute, hour, or day.
limit Maximum units allowed in the timeframe for this tier on your plan.
used Units already used in the current window.
remaining Units left before this tier returns HTTP 429.

Error codes

status error meaning what to do
400 invalid_json Body is not a valid JSON object. Send a valid JSON object payload and retry.
400 invalid_payload Request body could not be read. Retry with a valid JSON request body.
400 invalid_request Missing or invalid request fields. Fix the request payload before retrying.
400 immutable_channel Built-in email alert channel (channel_key email) is read-only; update, pause, and delete are not supported. Do not attempt to modify the built-in email channel.
401 unauthorized Missing or invalid bearer token. Send Authorization: Bearer YOUR_API_KEY.
403 access_denied The API key does not have API access. Use an API key with API access enabled.
403 capacity_exceeded Plan capacity limit reached. On create or resume: no capacity remains for that resource type. On monitor/heartbeat get, status, or view: account usage exceeds the plan limit - list, pause, and delete still work so you can reduce usage. List resources, pause or delete some to bring usage within your plan limit, then retry.
404 not_found Resource does not exist. Verify the resource id and retry.
405 method_not_allowed Use POST for API endpoints. Send a JSON POST request.
413 payload_too_large Request body exceeds the size limit. Reduce the request body size and retry.
429 rate_limited Too many requests for the endpoint tier. Response includes rate_limit with the current window state. Back off and retry later.
503 service_unavailable Temporary server-side failure. Retry with backoff.

Examples

rate_limited

{ "error": "rate_limited", "message": "Rate limit exceeded.", "rate_limit": { "tier": 2, "cost": 1, "timeframe": "minute", "limit": 120, "used": 73, "remaining": 47 } }

capacity_exceeded

{ "error": "capacity_exceeded", "message": "Your account exceeds its plan monitors capacity. List your monitors and pause or delete some to bring usage within your plan limit, then retry." }