Error codes and known API pitfalls

SchemaCopy Anchor Link

Monitor ownership error codesCopy Anchor Link

Since the managed vs. self-service model, monitor write endpoints of all types (website, DNS, ICMP, SMTP, SSH, FTP, IMAP/POP, domain, DNSBL) can return these 403 codes in data.code:

Monitor quota error codesCopy Anchor Link

An organization has a monitor quota. Creating a monitor while that quota is exhausted either fails, or, when the organization has automatic quota upgrading switched on, moves it to the next quota tier - and that tier has a higher monthly price, with the difference billed for the rest of the current period.

Customer package error codesCopy Anchor Link

POST /api/customers and PATCH /api/customers/:customerPublicId resolve the package a customer is on. Both reject a package the organization does not have:

PATCH previously stored an unknown packageType verbatim and left packageId empty. Such a customer was attached to no package config at all, which left its data retention unresolvable. Send packageId, or a packageType that exists on the organization.

Website check-interval error codesCopy Anchor Link

checkInterval is capped by the monitor's type, because the two meanings differ: for actively scheduled monitors it is the polling rate and stays at 1-1440 minutes (24 hours), while for heartbeat monitors it is the expected ping interval and accepts 1-43200 minutes (30 days), a monthly cron job is a legitimate monitor.

POST /api/websites reports the same ceiling as a validation issue on the checkInterval path rather than a data.code, because the type is known from the request body alone.

Website connect target (Ersatzziel) error codesCopy Anchor Link

connectHost, connectPort and connectTlsInsecure connect the check to a different host than the one in url, while url, the Host header and TLS SNI stay unchanged - the semantics of curl --resolve. Both POST /api/websites and PATCH /api/websites/:id (partial update included) validate them the same way.

Not available for playwright scenarios or heartbeat monitors: neither runs the HTTP/SSL check pipeline connectHost plugs into, so the fields are accepted on those monitors but have no effect.

Check mode error codes (SSH/SMTP/FTP/IMAP-POP monitors)Copy Anchor Link

The credentialed monitor kinds (SSH, SMTP, FTP, IMAP/POP) support a checkMode field (protocol | tcp, default protocol). In tcp mode the monitor performs a bare TCP port-reachability check and no credentials are required or stored. Create and update endpoints for these four kinds can return these 400 codes in data.code:

Incident error codesCopy Anchor Link

Only manual (status-page) incidents can be deleted. DELETE /api/incidents/:id returns this data.code:

Maintenance window error codesCopy Anchor Link

POST /api/maintenance-windows/preview-occurrences (docs) can return this data.code:

Creating, updating and deleting a window (POST /api/maintenance-windows, PATCH /api/maintenance-windows/{id}, DELETE /api/maintenance-windows/{id}) can return these:

A repeated create call is safe: a window whose whole request body matches one that already exists is not created a second time, the existing window is returned and its subscribers are not announced to twice.

Organization Reports error codesCopy Anchor Link

Endpoints under /api/organization/reports and /api/organization/report-runs can return these data.code values:

Data export error codesCopy Anchor Link

Endpoints under /api/organization/data-export (see Request Data Export) can return these data.code values:

Agent-auth error codesCopy Anchor Link

Agent access tokens (wsma_, see Agent authentication) are hard-gated to a GET/HEAD-only allowlist by default. A token minted with a write scope (api.write.monitors, api.write.incidents) is gated per method-and-path instead, against a fixed positive list covering only those two domains today -- everything else, including billing, credentials and any path on the shared write denylist, stays unreachable regardless of scope. Either kind of token still cannot see or reach anything outside its own read allowlist.

API token error codesCopy Anchor Link

A customer-scoped API token (wsm_ with a customerId) is confined to its customer. Organization-wide paths have no customer dimension, so the token cannot reach them at all: everything under /api/organizations/**, /api/organization/** (except GET /api/organization), /api/users/**, /api/admin/**, /api/platform-admin/**, /api/escalation-config/**, /api/custom-pricing, /api/custom-fields/**, /api/im/**, /api/notifications/send-alert, writes to /api/package-configs/**, creating or deleting customers, and /api/customers/bulk. No API token, customer-scoped or not, can create further tokens.

Claim flow error codesCopy Anchor Link

The service_auth registration and claim ceremony (see Claim flow) can return these error / data.code values, in addition to the base agent-auth codes above:

ID-JAG error codesCopy Anchor Link

identity_assertion registrations (see Identity assertion (ID-JAG)) can additionally return:

Connected apps (OAuth connections) error codesCopy Anchor Link

GET /api/oauth/connections and DELETE /api/oauth/connections/:clientId (see Connected apps) can return these data.code values, in addition to the standard 401 unauthorized:

OAuth consent error codesCopy Anchor Link

These codes come from the consent screen every OAuth/MCP authorization now passes through (POST, on /api/oauth/consent). Like the step-up and account-deletion routes, it is session-only and not part of the public API surface, and the method and the path are written apart here for the same reason: a METHOD /api/... route-line in these pages is what publishes an endpoint to /openapi.json. They are listed because the codes are what the screen and any support enquiry go by. The scope catalogue itself is on Connected apps.

The checks run in the order below, so the first one that fails is the code you get. The last row is the exception: it comes from Better Auth, after every check on this list has passed.

Status page subscriber error codesCopy Anchor Link

List, delete, and export endpoints for status page subscribers can return these data.code values, in addition to the standard 401 unauthorized and the two-tier statusPageNotFound behavior described on each page (a malformed or unknown :id is a code-less 400/404 from public-ID resolution; only an :id that resolves but fails the organization/customer-scope check carries data.code: statusPageNotFound):

Public IDs in DNS and DNSBL monitor routesCopy Anchor Link

The following path endpoints support public IDs in docs and client integrations:

• GET /api/customer-domains/:customerDomainPublicId
• PATCH /api/customer-domains/:customerDomainPublicId
• DELETE /api/customer-domains/:customerDomainPublicId
• GET /api/customer-ips/:customerIpPublicId
• PATCH /api/customer-ips/:customerIpPublicId
• DELETE /api/customer-ips/:customerIpPublicId

Legacy numeric IDs are still accepted for backward compatibility, but public IDs are the recommended integration format.

Incident Management (IM) API error codesCopy Anchor Link

The public Incident Management API (POST /api/im/events, GET/POST /api/im/incidents/**, GET /api/im/teams, GET/POST /api/im/schedules/**, GET /api/im/on-call) requires an organization-wide API token and can return these data.code values:

GET /api/im/incidents, Create Incident, the status/resolve endpoints, Schedules create, and Schedule Overrides add can also return the generic 400 invalidRequestBody for malformed input (e.g. an unknown status filter value, a non-integer :id, a missing/malformed rotation layer). POST /api/im/events can additionally return 429 Too Many Requests (600 requests/minute per organization, with a retryAfter field but no data.code), or 503 with data.code: unavailable if the event could not be queued, safe to retry.

User management error codesCopy Anchor Link

PATCH /api/users/:id (docs) and DELETE /api/users/:id (docs) protect the organization against locking itself out:

Tag error codesCopy Anchor Link

POST /api/tags records the human who created a tag in created_by, a column that is NOT NULL and carries no foreign key. A call arriving over an agent session (an MCP connection, create_tag) is therefore refused rather than given a substitute value, because writing anything else there would break the "creator may edit" branch of the permission check silently and permanently:

The rest of the tag surface (POST /api/tags, PATCH /api/tags/{id}, DELETE /api/tags/{id}, and attaching or detaching one with POST /api/monitor-tags and DELETE /api/monitor-tags) can return these:

Attaching a tag is idempotent: a tag already on the monitor is not attached a second time and the call still succeeds.

Change request error codesCopy Anchor Link

POST /api/monitors/:type/:id/change-requests and the legacy website-only route under /api/websites/:id/change-requests record the requesting human in requested_by, a NOT NULL column with a foreign key to user. A call over an agent session is refused rather than given a substitute value:

Notification channel error codesCopy Anchor Link

A Matrix channel is a special case worth knowing about: its homeserverUrl is checked for shape when the channel is saved and resolved again at delivery time. A homeserver that only resolves to a private or reserved address is refused at delivery, and the refusal is recorded against that alert rather than raised as an error on this endpoint.

Custom domain error codesCopy Anchor Link

The verify and activate endpoints of white-label domains and status page domains claim a hostname for your organization. Since 04.09.2026 a hostname is unique only among claimed entries (verified/active); a pending entry never blocks anyone and expires after 7 days.

404 for out-of-scope resourcesCopy Anchor Link

Since 04.09.2026 every resource endpoint answers 404 with its usual not-found code (websiteNotFound, monitorNotFound, customerNotFound, customerDomainNotFound, customerIpNotFound, statusPageNotFound) both when the resource does not exist and when it exists but is not within your organization or customer scope. A 403 is reserved for role-based denials (wrong role, customer-scoped token on an organization path). Tests that asserted 403 for "belongs to another customer" need updating.

Rate limit and size error codesCopy Anchor Link

POST /api/organizations/:id/vat-id/validate is limited to 10 checks per hour and organization (429 with data.retryAfter). POST /api/im/sources/:id/test-alert now applies the same body limits as the ingest URL (payloadTooLarge, invalidJson, payloadTooDeep).

Webhook and SMTP target error codesCopy Anchor Link

Organization suspended or deletedCopy Anchor Link

A gate ahead of the account-state gate below locks every /api/* call, a user session, a wsm_ API token, or a wsma_ agent access token alike, to the caller's organization status. Platform admins and supporters are exempt, the same way they are everywhere else.

A suspended organization gets 423 Organization suspended with no data.code, except for a narrow allowlist that stays reachable so it can pay its way back: reading the organization, updating its quota tier, the data export endpoints above, the tenant lookup, and the Mollie mandate return/reconcile and billing-discount routes. Every other route is blocked.

A deleted organization does not get that allowlist, and it also loses two routes the suspended case keeps: signing out (POST to /api/auth/sign-out) and both session bootstrap calls (GET on /api/auth/get-session and /api/_internal/auth/get-session) answer 423 Organization deleted with data.code organizationSuspended as well, deliberately, because signing out deletes the session row from Redis and that row is evidence for the deletion audit. Before 15.09.2026 a deleted organization's session, API token and agent token reached every route unchanged, the same gap this closes. "Deleted" here means status = 'deleted' OR the permanent deletion_completed_at marker is set. What decides this is whether the deletion has actually completed, not what status the organization currently displays. Two more surfaces follow the same rule: /mcp refuses a deleted organization's API tokens and OAuth connections with 423 before it builds a server, and no password reset e-mail is sent, the endpoint answers exactly as it does for an unknown address. A cancelled organization inside its grace period passes this gate unaffected only as long as its deletion has not actually completed. This gate takes effect within a few seconds rather than instantly, because the account state behind it is cached briefly.

Account state on the auth endpointsCopy Anchor Link

Better Auth's own routes (/api/auth/**, e.g. change-password, update-user, two-factor/*, mcp/token refresh) refuse a deactivated account or a suspended organization the same way the API does. Sign-in, sign-out, password reset, e-mail verification and get-session stay reachable. A deleted organization is narrower still: only sign-in, sign-up, password reset and e-mail verification stay reachable, sign-out and get-session answer 423 as described above, and a fresh sign-in fails anyway once credentials are checked, because session creation itself refuses.

MFA error codesCopy Anchor Link

These error codes are specific to two-step verification (MFA) and can be returned by otherwise unrelated endpoints once the underlying gate applies:

These codes are data.code values on the JSON error body, alongside the listed HTTP status.

Account deletion error codesCopy Anchor Link

These codes come from the in-app account deletion (GET, POST and DELETE, on /api/account/deletion-request). Like the step-up endpoint above, those routes are session-only and not part of the public API surface, and the method and the path are written apart here for the same reason: a METHOD /api/... route-line in these pages is what publishes an endpoint to /openapi.json, they are listed here because the codes are what the app and any support enquiry go by.

A deletion is requested, not performed on the spot: the request sets a deadline 30 days out and can be withdrawn until then. The organization's administrators are notified when it is requested and when it is withdrawn, because they are the people who can backfill an on-call rotation the departure would leave open.

VAT ID validation error codesCopy Anchor Link

POST /api/organizations/:organizationPublicId/vat-id/validate (see Validate VAT ID) can return these data.code values, in addition to the standard 401 unauthorized, 403 forbidden and 404 organizationNotFound:

Update Billing Details: required bodyCopy Anchor Link

Endpoint:

• PATCH /api/organizations/:organizationPublicId/billing

Currently supported request body:

{
  "billingEmail": "billing@deinkunde.com"
}

This endpoint currently accepts only billingEmail.