13.7Errors

A failed call returns an HTTP status code and a JSON body with a code and a message:

json

{"code": "invalid_argument", "message": "invalid input: name required"}

code	HTTP	Meaning	What to do
`unauthenticated`	401	No key, a revoked key, or a mistyped key.	Check the `Authorization` header.
`permission_denied`	403	The call works only in the dashboard (13.2). Or: the key is read-only and the call changes something (`this API key is read-only`). Or: you tried to delete a maintenance window that obsrvly set for your team.	Do it in the dashboard or with a full-access key, or leave the window.
`invalid_argument`	400	The request is wrong. The message says how.	Fix the field and send again.
`not_found`	404	Nothing with that ID in your team.	Check the ID.
`already_exists`	409	The name is taken, such as a secret's name or a status page's address.	Choose another name.
`failed_precondition`	400	Your plan does not allow it: monitor count, monitor type or interval. Also: a suspended team, acknowledging a resolved incident, or running a paused monitor.	Change the request. See the messages below.
`resource_exhausted`	429	A team limit (secrets, keys, channels, maintenance windows), or too many requests.	Delete what you no longer need, or wait and retry (13.4).
`unavailable`	503	A create, or a run-now check, could not be handled right now.	Send it again.
`internal`	500	A fault on our side. The message is always `internal error`.	Retry later (13.5). If it repeats, send us the `X-Request-Id`.

A not_found looks the same whether the item does not exist or belongs to another team.

Messages you may see#

Message	What it means
`invalid input: …`	A field is wrong, such as `invalid input: name required`, `invalid input: url required` or `invalid input: interval_seconds must be > 0`.
`monitor quota exceeded: 10/10 monitors used on the current plan`	Your plan has no room for another monitor. The numbers vary.
`… browser monitors require Pro or Business`	Your plan does not include browser monitors. API monitors give the same kind of message.
`… the current plan checks at most every 60s; 30s was requested`	The interval is shorter than your plan allows. The numbers vary.
`this workspace is suspended — contact support`	Your team is suspended. Contact support.
`monitor is paused — resume it before running a check`	Resume the monitor first (3.3).
`this monitor type is not dispatched — it reports in on its own`	Run now does not work on heartbeat monitors.
`monitor does not run from "<loc>"`	The `location` is not one of the monitor's regions.
`incident already resolved`	You cannot acknowledge a resolved incident.
`bad path` (400)	The address is wrong. Check it against 13.1.
`upstream unreachable` (502)	obsrvly could not be reached. Check first, then retry (13.5).

Maintenance windows have their own messages:

ends_at must be after starts_at
the window has already ended
a window can be at most 7 days long
a window can start at most 90 days ahead
a team can have at most 100 windows that have not ended

Other limits are checked when you save, and the message names the field. For example, renotifyIntervalSeconds must be 0 or 300–86400. Chapters 3, 5, 9 and 10 list the limits for each setting.