Errors Error envelope, status codes, and what each common code means.
Every error from the fastmon API uses the same envelope. The HTTP status code tells you the shape; the code inside tells you the cause.
{ "error" : { "code" : "validation_error" , "message" : "domain is required" , "request_id" : "01HZY…" , "doc_url" : "https://docs.fastmon.eu/errors/validation_error" , "details" : { "field" : "domain" } } } Field Required Notes codeyes Stable machine-readable code. Safe to switch on. messageyes Human-readable. May change for the same code as we improve clarity. request_idusually Same value as the X-Request-ID response header. doc_urloptional Link to a docs page that explains the code in depth. detailsoptional Code-specific. Validation errors put the offending field here.
Switch on code in client code; render message to humans. The code is part of our public contract; message may be reworded for clarity at any time.
Client errors (4xx) Server errors (5xx)
Status What it means 400The body or query was malformed. See code for specifics. 401Authentication failed or wasn't provided. See Authentication . 403Authenticated, but not allowed. Wrong organization, wrong role, or paused resource. 404Resource doesn't exist, or you can't see it. We don't leak existence. 409Conflict: usually a uniqueness violation or a state-machine clash. 422Validation failed. details.field carries the offending field. 429Rate-limited. Wait and retry; Retry-After is set.
Status What it means 500Server error. Include request_id when reporting. 502Bad gateway. Usually a deploy-window blip; retry with backoff. 503Service unavailable. Same as 502: transient. 504Gateway timeout. Retry once with longer client timeout.
The full list, grouped by category.
Code Meaning unauthenticatedNo credentials, or they didn't validate. invalid_credentialsEmail/password combination didn't match. two_factor_requiredLogin passed step one; a TOTP code is needed to complete the session. invalid_two_factor_codeThe TOTP code was wrong or expired. session_expiredThe session cookie is no longer valid. Log in again. invalid_tokenShort-lived opaque token (email verification, password reset, OAuth state, 2FA temp) was invalid or expired. Distinct from session_expired on purpose: don't bounce the user to /login on a stale reset link.
Code Meaning forbiddenAuthenticated, but not allowed for this action. organization_access_deniedThe token/user can't access this organization. site_access_deniedThe token/user can't access this site. admin_requiredThe action requires platform-admin privileges. owner_requiredThe action requires organization-owner privileges.
Code Meaning organization_not_foundOrganization doesn't exist or isn't visible to you. site_not_foundSite doesn't exist or isn't visible to you. release_not_foundRelease marker doesn't exist on this site. rule_not_foundNotification rule doesn't exist. member_not_foundOrganization member doesn't exist. invite_not_foundInvite doesn't exist or has been consumed. partner_not_foundPartner relationship doesn't exist. user_not_foundUser doesn't exist or isn't visible to you. resource_not_foundCatch-all for resources without a more specific code.
Code Meaning email_already_registeredSign-up attempted with an email that already has an account. site_already_existsDomain is already registered in this organization. release_already_existsA release with this version already exists on the site. organization_inactiveThe organization is suspended. user_inactiveThe user account is disabled. already_memberTried to invite or add someone who's already in the organization. billing_partner_existsBilling-partner relationship is already set; remove the existing one first. circular_partner_forbiddenPartner relationship would create a cycle. self_transfer_forbiddenCan't transfer ownership to yourself. conflictCatch-all conflict without a more specific code.
Code Meaning validation_errorA field failed validation. details.field names it. unsupported_operationThe operation isn't supported in this context (e.g. wrong storage mode). invalid_cursorThe pagination cursor was malformed or has expired.
Code Meaning rate_limitedToo many requests. Retry-After is set on the response.
Code Meaning plan_insufficientThe action requires a higher plan tier than the organization is on. ai_disabledAI features are turned off for this organization or globally. synthetic_disabledSynthetic Monitoring isn't enabled for this organization. An owner can turn it on under Organization Settings.
Code Meaning beacon_buffer_fullThe beacon ingestion buffer is saturated. Retry shortly. clickhouse_unavailableThe analytics store is temporarily unavailable. upstream_unavailableA required upstream service didn't respond. Retry with backoff. oauth_errorAn OAuth provider returned an error or the state didn't validate.
Code Meaning feature_removedThe endpoint or feature has been removed and no longer accepts requests.
Code Meaning internal_errorServer bug. Include request_id when reporting. not_readyService is starting up or briefly draining. Retry shortly.
Status Retry? 429Yes: wait Retry-After seconds. 502 / 503 / 504Yes: exponential backoff. Usually deploy-window blips. Other 5xx Once. If it persists, report with request_id. 4xxNo. The request is wrong; fix and resend.
Always include the request_id when you contact support. It lets us pull the matching server log in seconds. Without it, debugging starts from "describe what time it happened roughly," which is much slower.
The request ID is on:
the X-Request-ID response header,
error.request_id in the JSON body,the response of every successful request too (for chain correlation).
404 is intentionally ambiguous.404. We don't want to leak existence to unauthorized clients.Validation errors stop at the first failure. A payload with two bad fields reports one. Fix and resend to see the next.
