Error codes and known API pitfalls

This page documents real integration issues that have occurred in production or testing.

Schema

Error Code	Cause	Solution / Bug
`404 Website not found`	Some website sub-endpoints previously accepted only the legacy numeric website ID, even though the docs showed `websitePublicId`.	Fixed. `GET /api/websites/:websitePublicId/check-history` and `GET /api/websites/:websitePublicId/uptime-stats` now accept public IDs and still keep legacy-ID compatibility.
`403 Forbidden` on `GET /api/organizations/:organizationPublicId`	The route previously interpreted the path parameter directly as a number. A UUID therefore failed during permission checks.	Fixed. Organization detail and billing routes now resolve `publicId` correctly.
`400 Bad Request` with `ZodError` on `customer-ips` or `customer-domains`	Query parameters like `organizationId=`, `page=`, or `perPage=` were sent as empty strings. Zod coerced them to `0`, which then violated min constraints.	Fixed for `organizationId`, `page`, and `perPage`. Optional still means: omit unused parameters instead of sending empty strings.

Monitor ownership error codes

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:

Code	Meaning
`managed_by_organization`	A customer-scoped caller tried to edit/delete a `managed` monitor without the `canEditManaged` exception. Open a change request instead.
`selfServiceNotAllowed`	A customer-scoped caller tried to create a monitor but the customer's resolved `allowSelfService` is false.
`selfServiceQuotaReached`	Creating (or flipping to) a `self_service` monitor would exceed the customer's `maxSelfServiceUrls` — the quota counts all monitor types together.
`managementTypeOrgOnly`	A non-org-admin tried to change a monitor's `managementType`. Class flips are organization-admin-only.
`tooManyOpenRequests`	(`429`) The customer already has 10 open change requests.

Incident error codes

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

Code	Meaning
`notManualIncident`	(`403`) The incident is monitor-generated. Only manual incidents created by an admin can be deleted; automatic incidents are worker-owned and are never deletable via the API.

Organization Reports error codes

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

Code	Meaning
`invalidReportSchedule`	A weekly report is missing `weekday`, or a monthly report is missing `dayOfMonth` (1–28).
`invalidReportScope`	Report scope ids are not owned by the organization, or threshold mode has no threshold set.
`reportRunNotFound`	The requested report run does not exist for this organization.
`reportRunNoPdf`	The report run has no archived PDF (it was an email-only report or was skipped).

Public IDs in DNS and DNSBL monitor routes

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.

Update Billing Details: required body

Endpoint:

PATCH /api/organizations/:organizationPublicId/billing

Currently supported request body:

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

This endpoint currently accepts only billingEmail.