Reference

API errors

Common REST API error shapes and how clients should respond.

On this page

Common error strings
Rate limits
See also

Error responses carry a lowercase error string, and sometimes a code field:

json

{
  "error": "internal_error",
  "code": "INTERNAL"
}

The error value is a lowercase machine-readable string (for example forbidden, monitor_not_found, internal_error). Most errors return only error; a subset also include a short uppercase code (for example INTERNAL). There is no nested details object.

Common error strings

`error` value	HTTP status	Meaning
`unauthorized`	401	Missing, expired, or invalid authentication credential.
`forbidden`	403	Authenticated but lacking the required role or permission for this action.
`csrf_token_invalid`	403	The `X-CSRF-Token` header is missing or incorrect on a session-authenticated unsafe request (POST/PUT/PATCH/DELETE).
`<resource>_not_found` (for example `monitor_not_found`)	404	Resource does not exist, or you do not have permission to see it (IDOR returns 404, not 403).
`conflict`	409	Duplicate resource or conflicting state transition.
`mfa_already_enabled`	409	MFA setup was attempted while MFA is already active on the account.
`last_auth_method`	409	Attempting to unlink the last remaining sign-in method is not allowed.
`validation_failed`	422	Request body failed field validation.
`mfa_code_invalid`	401 (login) / 422 (setup verify)	Provided TOTP or backup code is incorrect or already used. MFA login returns 401; MFA setup verify returns 422.
`rate_limited`	429	Too many requests. See the `Retry-After` header for the window reset time.
`tier_limit_exceeded`	422	The action would exceed a numerical limit (e.g. monitor count) for the capability plan that gates it.
`tier_feature_not_available`	422	The feature requires a higher plan on the relevant capability (Uptime, On-call, or Status pages).
`email_not_verified`	403	Account email address has not been verified. Check inbox or request a new verification email.
`mfa_required`	200	Login succeeded for the first factor but a TOTP or backup code is still required. Response body carries `mfa_required: true` and a session token for the second step.
`invalid_grant`	400	OAuth token/refresh endpoint: the authorization code is invalid, expired, or already used (RFC 6749 format).
`internal_error`	500	Unexpected server error (returned with `code: "INTERNAL"`). Include the `X-Request-Id` header value when reporting.

Tier/feature-gate errors (tier_limit_exceeded, tier_feature_not_available) are returned as 422. A few endpoints (for example SSO) return a raw HTTP 402 Payment Required when a paid plan is needed; those bare 402 responses carry a human-readable error message.

Rate limits

Limits differ by endpoint class and runtime configuration. A limited request returns HTTP 429; use Retry-After before attempting it again. Do not build a client around one requests-per-minute number from documentation.

API errors

Common error strings

Rate limits

See also