Errors

The alarm endpoints answer with exactly three status codes. There is nothing else to handle. (The read-only integration endpoints return an ordinary 200 with the same envelope.)

Code	Meaning	Envelope
202	Accepted - the call will be applied	yes
401	The API key is missing or invalid	no - message only
404	The ID in the path is not one you can fire right now	yes

The Envelope

Every response except the 401 is the same four fields:

{
  "error": false,
  "message": null,
  "traceId": "8f14e45f-ea0d-4a1b-9f2c-6b3d70c5e881",
  "data": {
    "environment": "live",
    "location": { "id": "2c9wvhrq52k5refhtvmmr0f8yjz5j9e9", "name": "Home" }
  }
}

error is the outcome. message is human-readable and null on success. data carries the payload - environment and the alarm’s location on every 2xx. There is no status field: the HTTP status is already on the response, and echoing it into the body would create two sources of truth that can disagree.

traceId Is the Support Handle

Every enveloped response carries a traceId identifying that one call. Log it, and quote it when you report a problem - it is how one specific call gets found. It is not a resource reference; no endpoint accepts one back.

202 Does Not Mean an Alert Went Out

202 means the call was accepted and will be applied. A trigger that folds into an open incident, is cancelled inside the false alarm delay, or runs as a test is accepted and recorded without reaching anyone. If your automation depends on being live, check data.environment - a test alarm looks identical from the outside otherwise. See Incidents & Escalation.

401: The Key

The one response without the envelope - only a message, and no traceId because no call was ever traced:

{ "message": "Unauthorized" }

The key is missing, malformed, disabled, or deleted. Keys go in a header - X-API-Key, or Authorization: Bearer - never in the URL. See Authentication.

404: Not Yours to Fire Right Now

Your key is fine; the ID in the path is not one you can fire. Four cases, deliberately indistinguishable:

1. The ID does not exist.
2. It belongs to another account.
3. It is in your account, but your key is not scoped to it.
4. Your key can reach it, but it cannot currently fire - you disabled it, or a plan downgrade deactivated it.

Separating them would turn a narrowly-scoped key into a way to discover which IDs are real, so no response ever does. And a trigger that cannot fire is a 404 rather than a 202 on purpose: accepting the call and quietly doing nothing would tell you your alarm fired when it did not.

If a trigger returned 202 and nobody was alerted, that is not an error - see If Nobody Was Alerted.