Pingtower
Docs
Errors
Every non-2xx response is a JSON object with an error string. Some carry more.
{ "error": "validation failed",
"fields": [ { "field": "name", "message": "must not be empty", "rule": "required" } ] }
| Status | When | Extra fields |
|---|---|---|
400 | The body or a parameter failed validation. | fields[] with field, message, rule. |
401 | Bearer missing, malformed, or not the kind this route takes; or a wrong current_password on a route that re-checks it. | |
403 | Your role cannot do this: a member renaming a project, deleting a source or deleting a report, an admin inviting an owner, a responder editing a rule, a viewer acknowledging an alert, or any role whose permissions lack the one the route needs. A project-limited member on a route for unrestricted members only gets not available to project-limited members. | |
404 | Unknown project, source, rule, alert, or a tenant you are not a member of. A project-limited member gets the same unknown project for a project outside their grants, and unknown alert, unknown log line or unknown incident for one in a project they lack. | |
409 | Conflict. Deleting something a rule still names; removing the last owner; an email already taken; a disabled integration asked to test; editing a self-hosted box’s relay integration through anything but PUT /v1/relay; an invite or pairing code whose sender can no longer grant its role. | rules[] for a referenced source, action or schedule. |
422 | The request was well-formed but points at something that does not exist: a rule naming an unknown action, a schedule naming a non-member. Also a member’s project grants naming an unknown project, as validation failed with fields[]. Also an integration named pingtower.com relay, which is reserved. | errors[] when more than one. |
426 | client_outdated: the client is older than the tower’s required minimum for it. In Release 1 that is the addons agent below 0.4.0; the apps have no minimum yet. Upgrade the agent. See Client too old. | code, client, min_version. |
429 | Over a rate limit, a storage quota, or a count cap. | Retry-After header, whole seconds, on a rate limit only. |
500 | The daemon could not store or read. | |
503 | A request body took more than 60 seconds to arrive, or a test route was called on a daemon with no sender or executor configured. | Retry-After header on a slow body. |
The referenced-error shape
{ "error": "store: source is referenced by rules: gateway-timeouts, errors",
"rules": ["gateway-timeouts", "errors"] }
Returned on DELETE of a source, action or on-call schedule, and on renaming an action, while a rule still references it. Edit or delete those rules first.
Four kinds of 429
{"error": "rate limit exceeded"} is a rate limit, the plan’s or a password route’s; wait Retry-After and send again. {"error": "storage quota exceeded"} is the plan’s retained-rows cap, and waiting will not clear it; the line was still evaluated for alerting. project quota exceeded is the plan’s project cap, cleared only by deleting a project. An error that starts with a limit’s name, such as max_rules_per_project: a project may hold at most 500 rules and 500 exist, is a count cap: delete something before creating another.
Client too old
{ "error": "client version too old; update the app", "code": "client_outdated",
"client": "addons", "min_version": "0.4.0" }
The tower reads the client’s version from its User-Agent (pingtower-addons/0.4.0, pingtower-ios/…) and answers a client older than its required minimum with 426 and this body, on every /v1 route except the probe fleet’s /v1/fleet/. It does so before checking the token, so an outdated client is told to update, not to sign in again. In Release 1 the required minimum is 0.4.0 for the addons agent and none for the apps. Upgrade the agent to min_version or later; it is refused until then.
An agent from before 0.4.0 sends no version, and a build with a suffix such as 0.4.0-rc1 is not judged, so neither gets a 426. Upgrading to Release 1 says why the agent should still be upgraded.