Errors

A failure is a problem document (application/problem+json, RFC 9457) with an HTTP status and a stable code. Branch on code and status, never on the wording of detail.

{
  "type": "https://docs.watchtower15.com/api/errors/not_found/",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No server with that id exists in this organisation.",
  "request_id": "9b2c1f4e-…"
}

Field	Meaning
type	A link to the page that explains the code (the pages below).
title	A short name of the problem.
status	The HTTP status, repeated.
code	The stable machine-readable code.
detail	A sentence about this occurrence. It may change; do not parse it.
request_id	The id of this call, also sent as the X-Request-Id header. Quote it to support.
errors	Only on 422: the fields that were wrong, each with its messages.
limit, used	Only where a limit was reached: the limit and what was used.

The error codes

Code	Status
invalid_request	422	A parameter is missing or wrong.
not_found	404	No such record or operation.
unauthorized	401	The key is missing, malformed, expired or revoked.
forbidden	403	The key or its owner may not do this.
method_not_allowed	405	The operation does not take this method.
rate_limited	429	Too many calls too fast.
daily_limit_reached	429	The organisation’s daily call limit is used.
payment_required	402	The organisation has no valid payment method.
invoice_overdue	402	An invoice is overdue.
limit_reached	422	An account limit is reached.
held_limit_reached	422	The limit on servers waiting for approval is reached.
store_unavailable	503	A data store did not answer in time.
internal_error	500	Something unexpected went wrong on our side.

Answers from the host, before the API runs

The host in front of the API answers a few things itself, so they do not carry the fields above:

• A path outside /v1/ is a 404 problem document with no request_id and no X-Request-Id — the call never reached the API.
• A body over 1 MB is a 413, and a multipart body a 415. Both come back as a plain page, not a problem document. The API takes small JSON bodies only.