Error codes

Every error code a Norcube API problem response can carry, what it means and what to do about it.

Norcube Monitor's API answers every error with an RFC 9457 problem (application/problem+json). The type member is a link to the code's section on this page:

{
  "type": "https://docs.norcube.com/errors/limit-reached",
  "title": "Limit reached",
  "status": 403,
  "detail": "Your organization can have at most 10 monitors.",
  "instance": "urn:uuid:3f2c8a8e-6c1d-4a59-9a43-2b1f0f6f9d10",
  "code": "LIMIT_REACHED",
  "reason": "MONITOR_LIMIT",
  "data": { "limit": "10" },
  "timestamp": "2026-11-04T12:00:00Z"
}

Switch on code, and on reason where you act on the finer cause. Don't switch on detail, which is an English sentence for people. New codes and reasons are added over time, so treat a code you don't know by its HTTP status and a reason you don't know by its code.

instance holds the request id, also sent as the X-Request-ID header. Include it when you contact support.

Status	`code`	In short
400	`INVALID_PAYLOAD`	The request couldn't be read.
400	`VALIDATION_FAILED`	One or more fields are wrong.
401	`UNAUTHORIZED`	No valid sign-in.
402	`ORG_BLOCKED`	The organization has unpaid invoices.
403	`FORBIDDEN`	The caller lacks a permission or scope.
403	`LIMIT_REACHED`	The organization is at a limit.
404	`NOT_FOUND`	No such resource or route.
405	`METHOD_NOT_ALLOWED`	The route doesn't accept this method.
409	`ALREADY_EXISTS`	The resource already exists.
409	`CONFLICT`	The resource's state refuses the change.
409	`MANAGED_RESOURCE`	Another Norcube product manages the monitor.
413	`PAYLOAD_TOO_LARGE`	The request body is too large.
429	`TOO_MANY_REQUESTS`	A rate limit.
500	`INTERNAL_ERROR`	Something went wrong on Norcube's side.
503	`UNAVAILABLE`	A dependency failed. Retry.

Invalid request

INVALID_PAYLOAD, HTTP 400.

What it means: The request couldn't be read at all. The body isn't JSON, a query parameter has the wrong shape, a pagination cursor belongs to another sort, or the monitor's type can't be checked on demand.

What to do: Fix the request as detail says, and don't retry it unchanged. For a cursor from another sort, start again without it.

Validation failed

VALIDATION_FAILED, HTTP 400.

What it means: The request was readable, but fields are wrong. errors lists all of them, each with a pointer to the field, a rule, the rule's params when it has any, and a detail sentence. Bodies are decoded strictly, so an unknown or duplicate field or a value of the wrong type is an error too.

{
  "pointer": "/http/timeoutMs",
  "rule": "range",
  "params": { "min": 1000, "max": 30000 },
  "detail": "must be between 1000 and 30000"
}

What to do: Fix each listed field. Treat a rule you don't know as a generic invalid value and show its detail.

`reason`	What it means
`CHANNEL_TYPE_UNAVAILABLE`	This alert channel kind isn't offered. `data.kind` names it.

Authentication required

UNAUTHORIZED, HTTP 401.

What it means: The request has no valid token, or the token doesn't name an organization.

What to do: Sign in again or send a fresh token. Retrying with the same token won't help.

`reason`	What it means
`MISSING_ORGANIZATION_ID`	The token names no organization.

Organization blocked

ORG_BLOCKED, HTTP 402.

What it means: The organization has unpaid invoices. On-demand checks, new monitors, test sends, verification codes, creating or publishing status pages, and setting a custom domain are refused.

What to do: Pay the open invoices or add a payment method in billing, then try again.

Forbidden

FORBIDDEN, HTTP 403.

What it means: The caller is known, but isn't allowed to do this.

What to do: Ask an organization admin for the permission, or use a token with the right scope. See Members and IAM and CI tokens.

`reason`	What it means
`INSUFFICIENT_SCOPE`	The scopes of a CI token or an MCP connection don't cover the request.

Limit reached

LIMIT_REACHED, HTTP 403.

What it means: The organization is at a limit. data.limit holds the number.

What to do: Remove something you no longer need, or raise the limit. Retrying won't help until the count changes. See Limits.

`reason`	What it counts
`MONITOR_LIMIT`	Monitors.
`ALERT_CHANNEL_LIMIT`	Alert channels.
`UNVERIFIED_CHANNEL_LIMIT`	Channels whose contact isn't verified yet. Verify or remove one.
`STATUS_PAGE_LIMIT`	Status pages.
`STATUS_PAGE_DOMAIN_LIMIT`	Status page custom domains.

Not found

NOT_FOUND, HTTP 404.

What it means: There's no such resource or route. Another organization's resource and a malformed id get the same answer, so an id can't be probed.

What to do: Check the id, the path and the organization your token belongs to.

`reason`	What it means
`DOMAIN_NOT_SET`	The status page exists but has no custom domain.

Method not allowed

METHOD_NOT_ALLOWED, HTTP 405.

What it means: The path exists, but not with this HTTP method.

What to do: Use the method listed in the API reference.

Already exists

ALREADY_EXISTS, HTTP 409.

What it means: The resource already has a monitor of this type.

What to do: Use the existing monitor instead of creating another one.

Conflict

CONFLICT, HTTP 409.

What it means: The resource's current state refuses the change. reason says why.

What to do: Act on the reason below. Retrying unchanged won't help, except where the reason says to wait.

`reason`	What it means	What to do
`SLUG_TAKEN`	Another page has this address, or used it recently.	Pick a different slug.
`DOMAIN_TAKEN`	Another status page has proved it owns the hostname.	Use another hostname, or have the other page release it.
`DOMAINS_DISABLED`	Custom domains aren't available on this deployment.	Use the page's default address.
`INCIDENT_RESOLVED`	The posted incident is resolved.	Post a new incident.
`NOTHING_TO_VERIFY`	This channel has nothing to verify.	Nothing. No verification is needed.
`ALREADY_VERIFIED`	The channel is already verified.	Nothing.
`CODE_RECENTLY_SENT`	A verification code was just sent.	Wait a minute before asking for another.
`CODE_EXPIRED`	The verification code has expired.	Ask for a new code.
`TOO_MANY_ATTEMPTS`	Too many wrong codes.	Ask for a new code.
`CONTACT_UNVERIFIED`	The channel's contact isn't verified.	Verify it before sending a test.
`DELIVERY_REJECTED`	The provider refused the message for good.	Fix the number or webhook.
`CHANNEL_TYPE_UNAVAILABLE`	Voice-call alerts aren't available. `data.kind` names the kind.	Use an SMS channel.

Managed by another service

MANAGED_RESOURCE, HTTP 409.

What it means: The monitor belongs to a resource in another Norcube product, such as a DomainRadar saved domain, and can't be deleted here.

What to do: Change it where it's managed. detail names the place.

Request too large

PAYLOAD_TOO_LARGE, HTTP 413.

What it means: The request body is over the server's limit.

What to do: Send a smaller body.

Too many requests

TOO_MANY_REQUESTS, HTTP 429.

What it means: A per-user or per-organization rate limit. See rate limits.

What to do: Wait for the time in the Retry-After header, then try again.

Internal error

INTERNAL_ERROR, HTTP 500.

What it means: Something went wrong on Norcube's side. detail says only "Something went wrong." Internal details never reach the response.

What to do: Try again shortly. If it keeps happening, contact support with the instance value.

Service unavailable

UNAVAILABLE, HTTP 503.

What it means: A service Norcube Monitor depends on couldn't be reached or failed.

What to do: Retry, with a growing delay between attempts.

Error codes

On this page