# Errors > The up4 API error envelope, how to retry, and every error code with its meaning, trigger, fix and the operations that can return it. Source: https://upfour.io/docs/api/errors Every failed request returns one JSON shape and a stable code. Branch on the code, retry only what is worth retrying, and keep the request id. ## The error envelope A 4xx or 5xx response from a `/v1` operation has this body, with one exception noted below: ```json { "error": { "code": "import_rows_out_of_range", "message": "Choose between 1 and 500 rows per import.", "request_id": "req_…", "details": { "min_rows": 1, "max_rows": 500 } } } ``` | Field | Meaning | | --- | --- | | `code` | A stable snake_case identifier. Branch on this, not on the message. | | `message` | A sentence for people. Its wording can change; do not match on it. The message of a 5xx is replaced by Internal server error, except for 503 and a few provider failures; the cause stays in our log. | | `request_id` | The id of this request. Quote it when you contact support; it finds the request in our logs. | | `details` | Optional. Extra data some codes define, such as `max_bytes` or `retry_at`. Absent when a code has none. | A code that no handler names comes from its HTTP status: `bad_request` for 400, `unauthorized` for 401, `payment_required` for 402, `permission_denied` for 403, `not_found` for 404, `conflict` for 409, `rate_limit_exceeded` for 429, `service_unavailable` for 503, `internal_error` for other 5xx and `request_failed` for any other status. The incident AI operations are an exception: a 402 for a used-up AI quota still has the older flat body `{"error": "…", "quota": {…}}`, where `error` is a string. Read the HTTP status there. ## Handling errors - Branch on `error.code`. The message and the details text are for people. - Retry only **429** and **5xx**. Any other 4xx fails the same way until you change the request. - Wait for the `Retry-After` header when there is one. It gives seconds and comes with `rate_limit_exceeded`, `confirmation_rate_limited` and the 429 form of `quota_limit_reached`. Without it, back off exponentially and add jitter. - Send an `Idempotency-Key` on every POST and PATCH you may retry. When the first request finished with a status from 200 to 499, a retry after a timeout gets that stored answer and creates nothing a second time. A **5xx is not stored**: a retry with the same key runs the request again, so after a 5xx look at the resource before you assume nothing was created. See [idempotency](https://upfour.io/docs/api/idempotency.md). - Log `request_id` with the code, and send it to support for any 5xx that persists. ## Errors on every operation Middleware, not a handler, answers these before a request reaches its operation, so they are listed here once and not on each operation. Each applies only under the condition shown. | Code | Status | When | | --- | --- | --- | | [api_key_scopes_required](https://upfour.io/docs/api/errors#code-api_key_scopes_required) | 403 | The request uses an API key created before scopes existed. | | [bad_request](https://upfour.io/docs/api/errors#code-bad_request) | 400 | A POST or PATCH carries an Idempotency-Key header and its body cannot be read. | | [forbidden](https://upfour.io/docs/api/errors#code-forbidden) | 403 | A POST or PATCH carries an Idempotency-Key header and the request has no verifiable current authorization. | | [idempotency_key_conflict](https://upfour.io/docs/api/errors#code-idempotency_key_conflict) | 409 | A POST or PATCH carries an Idempotency-Key header that was stored with a different body. | | [idempotency_replay_unavailable](https://upfour.io/docs/api/errors#code-idempotency_replay_unavailable) | 409 | A POST or PATCH carries an Idempotency-Key header whose stored response cannot be replayed to this caller. | | [insufficient_scope](https://upfour.io/docs/api/errors#code-insufficient_scope) | 403 | The request uses an API key that lacks the scope the operation requires. | | [internal_error](https://upfour.io/docs/api/errors#code-internal_error) | 500 · 502 | A POST or PATCH carries an Idempotency-Key header and the key store fails. | | [not_found](https://upfour.io/docs/api/errors#code-not_found) | 404 | A client-portal session requests a route the portal does not expose. | | [permission_denied](https://upfour.io/docs/api/errors#code-permission_denied) | 403 | A browser session sends a request from another origin; Bearer keys are not affected. | | [rate_limit_exceeded](https://upfour.io/docs/api/errors#code-rate_limit_exceeded) | 429 | The request exceeds the per-client rate limit, or the per-credential limit once authenticated; Retry-After gives the wait in seconds. | | [read_only_api_key](https://upfour.io/docs/api/errors#code-read_only_api_key) | 403 | A read-only API key calls an operation that writes. | | [session_required](https://upfour.io/docs/api/errors#code-session_required) | 403 | An API key calls a route that is limited to browser sessions. | | [unauthorized](https://upfour.io/docs/api/errors#code-unauthorized) | 401 | The credentials are missing, malformed, unknown, revoked or expired. | ## Error codes by status 67 codes can come back from a public operation. Each is listed under its first HTTP status; a code that can carry another status shows it next to the code. “Operations” are the ones whose handler can answer with the code, found by reading the source; the page of an operation in the [reference](https://upfour.io/docs/api.md) is authoritative for what it returns. [200](https://upfour.io/docs/api/errors#status-200)[400](https://upfour.io/docs/api/errors#status-400)[401](https://upfour.io/docs/api/errors#status-401)[402](https://upfour.io/docs/api/errors#status-402)[403](https://upfour.io/docs/api/errors#status-403)[404](https://upfour.io/docs/api/errors#status-404)[409](https://upfour.io/docs/api/errors#status-409)[413](https://upfour.io/docs/api/errors#status-413)[422](https://upfour.io/docs/api/errors#status-422)[429](https://upfour.io/docs/api/errors#status-429)[500](https://upfour.io/docs/api/errors#status-500)[502](https://upfour.io/docs/api/errors#status-502)[503](https://upfour.io/docs/api/errors#status-503)[504](https://upfour.io/docs/api/errors#status-504) ### 200 #### [request_failed](https://upfour.io/docs/api/errors#code-request_failed) 200 · 410 · 413 · 422 The request failed with a status that has no code of its own. - **Typical trigger:** A 410 for an expired invite, a 413 for a body over its size limit, or a 422 for a request that parses but that the rules reject. - **Fix:** Use the HTTP status and message; these are not retryable until the request changes. - **Operations:** - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) - [POST /status-page-design-templates](https://upfour.io/docs/api/status-page-design-templates#post_status_page_design_templates) - [PUT /status-page-design-templates/{templateID}](https://upfour.io/docs/api/status-page-design-templates#put_status_page_design_templates_templateID) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) ### 400 Bad request #### [attachment_empty](https://upfour.io/docs/api/errors#code-attachment_empty) The attachment file is empty. - **Typical trigger:** Uploading an incident attachment of zero bytes. - **Fix:** Upload a file that has content. - **Operations:** - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) #### [attachment_type_unsupported](https://upfour.io/docs/api/errors#code-attachment_type_unsupported) The attachment's file type is not accepted. - **Typical trigger:** Uploading an incident attachment whose MIME type is not on the allowed list. - **Fix:** Upload a file of an allowed type. - **Operations:** - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) #### [bad_request](https://upfour.io/docs/api/errors#code-bad_request) The request is malformed or fails validation. - **Typical trigger:** A body that is not valid JSON, a missing or invalid field, or a path or query value that does not parse; the message names the problem. - **Fix:** Read message and details, correct the request and send it again; an unchanged retry fails the same way. - **Operations:** Under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation), and from handlers on 267 of 271 operations. #### [cursor_expired](https://upfour.io/docs/api/errors#code-cursor_expired) The list cursor has expired. - **Typical trigger:** Paging a monitor list with a cursor that is too old. - **Fix:** Start again without a cursor. - **Operations:** - [GET /monitors](https://upfour.io/docs/api/monitors#get_monitors) #### [cursor_invalid](https://upfour.io/docs/api/errors#code-cursor_invalid) The list cursor is not valid. - **Typical trigger:** Paging a monitor list with a cursor that was not issued by the API or was altered. - **Fix:** Use the cursor from the previous response unchanged, or start without one. - **Operations:** - [GET /monitors](https://upfour.io/docs/api/monitors#get_monitors) #### [cursor_parameters_changed](https://upfour.io/docs/api/errors#code-cursor_parameters_changed) The filters changed since the cursor was issued. - **Typical trigger:** Paging a monitor list with a cursor while sort or filter parameters differ from the first request. - **Fix:** Keep the parameters the same for all pages, or start again without a cursor. - **Operations:** - [GET /monitors](https://upfour.io/docs/api/monitors#get_monitors) #### [file_empty](https://upfour.io/docs/api/errors#code-file_empty) The uploaded file is empty. - **Typical trigger:** Uploading a logo or image with no content. - **Fix:** Upload a file that has content. - **Operations:** - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) #### [file_type_unsupported](https://upfour.io/docs/api/errors#code-file_type_unsupported) The file's type is not accepted for this upload. - **Typical trigger:** Uploading a file whose type is not one of the formats the operation accepts; details.formats lists them. - **Fix:** Upload a file in one of details.formats. - **Operations:** - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) #### [image_dimensions_too_large](https://upfour.io/docs/api/errors#code-image_dimensions_too_large) The image has more pixels than allowed. - **Typical trigger:** Uploading an image with more pixels than details.max_pixels. - **Fix:** Scale the image down and upload it again. - **Operations:** - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) #### [image_invalid](https://upfour.io/docs/api/errors#code-image_invalid) The file is not a readable image. - **Typical trigger:** Uploading a file with an image type that cannot be decoded. - **Fix:** Export the image again and upload the new file. - **Operations:** - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) #### [import_invalid](https://upfour.io/docs/api/errors#code-import_invalid) The import body is not valid. - **Typical trigger:** A batch monitor import whose body cannot be parsed; the message names the problem. - **Fix:** Correct the body and send it again. - **Operations:** - [POST /monitors/batch](https://upfour.io/docs/api/monitors#post_monitors_batch) - [POST /monitors/batch/dry-run](https://upfour.io/docs/api/monitors#post_monitors_batch_dry_run) #### [import_rows_out_of_range](https://upfour.io/docs/api/errors#code-import_rows_out_of_range) The import has too few or too many rows. - **Typical trigger:** A batch monitor import with fewer than min_rows or more than max_rows rows, both in details. - **Fix:** Send between min_rows and max_rows rows per request. - **Operations:** - [POST /monitors/batch](https://upfour.io/docs/api/monitors#post_monitors_batch) - [POST /monitors/batch/dry-run](https://upfour.io/docs/api/monitors#post_monitors_batch_dry_run) #### [invalid_move_source](https://upfour.io/docs/api/errors#code-invalid_move_source) The page to move the domain from is not valid. - **Typical trigger:** Setting a domain with a move-from page id that is not a status page the caller can use. - **Fix:** Send the id of the status page that holds the domain. - **Operations:** - [PUT /status-pages/{pageID}/custom-domain](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_custom_domain) #### [logo_fetch_failed](https://upfour.io/docs/api/errors#code-logo_fetch_failed) The logo could not be fetched from the address given. - **Typical trigger:** Importing a client logo from a URL that cannot be reached or that does not return an acceptable image. - **Fix:** Check the URL, or upload the logo file instead. - **Operations:** - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [POST /clients/logo-import](https://upfour.io/docs/api/clients#post_clients_logo_import) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) #### [no_channels_linked](https://upfour.io/docs/api/errors#code-no_channels_linked) The monitor has no alert channel to send a test to. - **Typical trigger:** A test alert for a monitor that has no alert channel linked. - **Fix:** Link an alert channel to the monitor and test again. - **Operations:** - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) #### [svg_unsafe](https://upfour.io/docs/api/errors#code-svg_unsafe) The SVG contains content that is not allowed. - **Typical trigger:** Uploading an SVG that contains a script, a foreignObject, a javascript: URL, an event-handler attribute or an external href. - **Fix:** Remove those parts from the SVG, or upload a PNG or JPEG. - **Operations:** - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) #### [upload_invalid](https://upfour.io/docs/api/errors#code-upload_invalid) The upload could not be read as a multipart form. - **Typical trigger:** A body that is not a valid multipart form, or whose file cannot be parsed. - **Fix:** Send a well-formed multipart/form-data request. - **Operations:** 7 operations - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) #### [upload_no_file](https://upfour.io/docs/api/errors#code-upload_no_file) The multipart request has no file part. - **Typical trigger:** An upload request without a file field. - **Fix:** Send the file as multipart/form-data in the field the operation names. - **Operations:** 7 operations - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) ### 401 Unauthorized #### [unauthorized](https://upfour.io/docs/api/errors#code-unauthorized) The request carries no valid credentials. - **Typical trigger:** The Authorization header is missing or malformed, the API key is unknown or revoked, or a browser session has expired. - **Fix:** Send a valid key as Authorization: Bearer pls\_..., and create a new key if the old one was revoked. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). Handlers also return it on: - [GET /incidents/{incidentID}/ai](https://upfour.io/docs/api/incidents#get_incidents_incidentID_ai) - [POST /incidents/{incidentID}/ai/postmortem](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_postmortem) - [POST /incidents/{incidentID}/ai/summary](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_summary) - [PUT /incidents/{incidentID}/ai/{kind}/rating](https://upfour.io/docs/api/incidents#put_incidents_incidentID_ai_kind_rating) ### 402 Payment required #### [ai_billing_blocked](https://upfour.io/docs/api/errors#code-ai_billing_blocked) AI features are switched off because the Company has no active credit. - **Typical trigger:** An AI summary or postmortem request while the Company has no active credit. - **Fix:** Top up the credit, then retry. - **Operations:** - [GET /incidents/{incidentID}/ai](https://upfour.io/docs/api/incidents#get_incidents_incidentID_ai) - [POST /incidents/{incidentID}/ai/postmortem](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_postmortem) - [POST /incidents/{incidentID}/ai/summary](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_summary) - [PUT /incidents/{incidentID}/ai/{kind}/rating](https://upfour.io/docs/api/incidents#put_incidents_incidentID_ai_kind_rating) - [PUT /organization/ai-quota](https://upfour.io/docs/api/organization#put_organization_ai_quota) - [GET /organization/ai-usage](https://upfour.io/docs/api/organization#get_organization_ai_usage) #### [billing_action_unavailable](https://upfour.io/docs/api/errors#code-billing_action_unavailable) The Company's billing state does not allow this action. - **Typical trigger:** A metered or limited action while the billing state, such as paused or without credit, blocks it; details holds the action and billing_state. - **Fix:** Top up the credit or change the plan, then retry. - **Operations:** 21 operations - [POST /escalation-policies](https://upfour.io/docs/api/escalation-policies#post_escalation_policies) - [PUT /escalation-policies/{policyID}](https://upfour.io/docs/api/escalation-policies#put_escalation_policies_policyID) - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) - [POST /invites](https://upfour.io/docs/api/invites#post_invites) - [POST /invites/{inviteID}/resend](https://upfour.io/docs/api/invites#post_invites_inviteID_resend) - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) - [POST /reports/schedules](https://upfour.io/docs/api/reports#post_reports_schedules) - [PUT /reports/schedules/{scheduleID}](https://upfour.io/docs/api/reports#put_reports_schedules_scheduleID) - [POST /reports/schedules/{scheduleID}/run-now](https://upfour.io/docs/api/reports#post_reports_schedules_scheduleID_run_now) - [POST /reports/{runID}/share](https://upfour.io/docs/api/reports#post_reports_runID_share) - [POST /status-pages](https://upfour.io/docs/api/status-pages#post_status_pages) - [POST /status-pages/{pageID}/sections/{sectionID}/resources](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_sections_sectionID_resources) - [PUT /status-pages/{pageID}/sections/{sectionID}/resources/{resourceID}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_sections_sectionID_resources_resourceID) - [PUT /status-pages/{pageID}/structure](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_structure) - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) - [POST /webhook-subscriptions](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions) - [POST /webhook-subscriptions/{subscriptionID}/redeliver/{deliveryID}](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions_subscriptionID_redeliver_deliveryID) - [POST /webhook-subscriptions/{subscriptionID}/test](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions_subscriptionID_test) #### [payment_required](https://upfour.io/docs/api/errors#code-payment_required) The Company's billing state does not allow the action. - **Typical trigger:** Creating a monitor, scheduled job or alert channel when the credit is used up or the plan does not cover it; the message names the reason. - **Fix:** Top up the credit or change the plan in billing, then retry. - **Operations:** 9 operations - [POST /heartbeats](https://upfour.io/docs/api/heartbeats#post_heartbeats) - [POST /monitors](https://upfour.io/docs/api/monitors#post_monitors) - [PUT /monitors/{monitorID}](https://upfour.io/docs/api/monitors#put_monitors_monitorID) - [PATCH /monitors/{monitorID}](https://upfour.io/docs/api/monitors#patch_monitors_monitorID) - [POST /monitors/{monitorID}/resume](https://upfour.io/docs/api/monitors#post_monitors_monitorID_resume) - [POST /notification_channels](https://upfour.io/docs/api/notification-channels#post_notification_channels) - [POST /status-pages](https://upfour.io/docs/api/status-pages#post_status_pages) - [PUT /status-pages/{pageID}/custom-domain](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_custom_domain) - [POST /status-pages/{pageID}/duplicate](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_duplicate) #### [subscriber_import_requires_payment](https://upfour.io/docs/api/errors#code-subscriber_import_requires_payment) Subscriber import is locked while the Company is on its starting credit. - **Typical trigger:** Importing subscribers before the first payment. - **Fix:** Top up the credit, then import. - **Operations:** - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) ### 403 Forbidden #### [api_key_scopes_required](https://upfour.io/docs/api/errors#code-api_key_scopes_required) The API key predates scopes and has none. - **Typical trigger:** Only for API keys created before scopes existed, on any public operation. - **Fix:** Rotate the key in the app to get one with explicit scopes. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). #### [check_capacity_exceeded](https://upfour.io/docs/api/errors#code-check_capacity_exceeded) The change would push the subscription's projected monthly check load over its included budget. - **Typical trigger:** Creating a monitor, directly or through a client template, or changing one, when the projected cost including the change exceeds the budget; running monitors are not affected, and details carries projected_cents, included_cents and change_cents. - **Fix:** Use a longer interval, fewer regions or fewer monitors, or raise the included budget. - **Operations:** 7 operations - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [POST /monitors](https://upfour.io/docs/api/monitors#post_monitors) - [PUT /monitors/{monitorID}](https://upfour.io/docs/api/monitors#put_monitors_monitorID) - [PATCH /monitors/{monitorID}](https://upfour.io/docs/api/monitors#patch_monitors_monitorID) - [POST /monitors/{monitorID}/check](https://upfour.io/docs/api/monitors#post_monitors_monitorID_check) - [POST /monitors/{monitorID}/pause](https://upfour.io/docs/api/monitors#post_monitors_monitorID_pause) - [POST /monitors/{monitorID}/resume](https://upfour.io/docs/api/monitors#post_monitors_monitorID_resume) #### [feature_disabled](https://upfour.io/docs/api/errors#code-feature_disabled) The monitor uses a feature that is currently switched off. - **Typical trigger:** Saving a monitor whose configuration needs a feature the platform has disabled; the saved configuration stays as it was. - **Fix:** Remove that feature from the monitor, or try again once the feature is back. - **Operations:** - [POST /monitors](https://upfour.io/docs/api/monitors#post_monitors) - [PUT /monitors/{monitorID}](https://upfour.io/docs/api/monitors#put_monitors_monitorID) - [PATCH /monitors/{monitorID}](https://upfour.io/docs/api/monitors#patch_monitors_monitorID) - [POST /monitors/{monitorID}/check](https://upfour.io/docs/api/monitors#post_monitors_monitorID_check) - [POST /monitors/{monitorID}/pause](https://upfour.io/docs/api/monitors#post_monitors_monitorID_pause) - [POST /monitors/{monitorID}/resume](https://upfour.io/docs/api/monitors#post_monitors_monitorID_resume) #### [forbidden](https://upfour.io/docs/api/errors#code-forbidden) The idempotency layer has no current authorization to bind the key to. - **Typical trigger:** Only on POST and PATCH requests that send an Idempotency-Key header and whose authorization cannot be verified. - **Fix:** Authenticate the request with a valid key before sending Idempotency-Key. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). #### [insufficient_scope](https://upfour.io/docs/api/errors#code-insufficient_scope) The API key lacks the scope this operation needs. - **Typical trigger:** Only for API keys, when the key's scopes do not include the one the operation requires; details.required_scope names it. - **Fix:** Create a key with the needed scope; a missing scope never resolves by retrying. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). #### [permission_denied](https://upfour.io/docs/api/errors#code-permission_denied) The credentials are valid but may not do this. - **Typical trigger:** The key's role or client scope does not allow the action, for example a write on a client the key cannot write to. - **Fix:** Use a key with the needed role and client scope, or ask a Company admin to grant it. - **Operations:** Under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation), and from handlers on 182 of 271 operations. #### [quota_limit_reached](https://upfour.io/docs/api/errors#code-quota_limit_reached) 403 · 429 A usage or inventory limit of the Company was reached. - **Typical trigger:** Counters and concurrency limits answer 429 with Retry-After, inventory and capacity limits answer 403; details holds purpose, limit and window. - **Fix:** On 429 wait Retry-After seconds; on 403 free something up, request a higher limit where details.raise_request is true, or buy an extension. - **Operations:** 21 operations - [POST /escalation-policies](https://upfour.io/docs/api/escalation-policies#post_escalation_policies) - [PUT /escalation-policies/{policyID}](https://upfour.io/docs/api/escalation-policies#put_escalation_policies_policyID) - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) - [POST /invites](https://upfour.io/docs/api/invites#post_invites) - [POST /invites/{inviteID}/resend](https://upfour.io/docs/api/invites#post_invites_inviteID_resend) - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) - [POST /reports/schedules](https://upfour.io/docs/api/reports#post_reports_schedules) - [PUT /reports/schedules/{scheduleID}](https://upfour.io/docs/api/reports#put_reports_schedules_scheduleID) - [POST /reports/schedules/{scheduleID}/run-now](https://upfour.io/docs/api/reports#post_reports_schedules_scheduleID_run_now) - [POST /reports/{runID}/share](https://upfour.io/docs/api/reports#post_reports_runID_share) - [POST /status-pages](https://upfour.io/docs/api/status-pages#post_status_pages) - [POST /status-pages/{pageID}/sections/{sectionID}/resources](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_sections_sectionID_resources) - [PUT /status-pages/{pageID}/sections/{sectionID}/resources/{resourceID}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_sections_sectionID_resources_resourceID) - [PUT /status-pages/{pageID}/structure](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_structure) - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) - [POST /webhook-subscriptions](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions) - [POST /webhook-subscriptions/{subscriptionID}/redeliver/{deliveryID}](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions_subscriptionID_redeliver_deliveryID) - [POST /webhook-subscriptions/{subscriptionID}/test](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions_subscriptionID_test) #### [read_only_api_key](https://upfour.io/docs/api/errors#code-read_only_api_key) A read-only API key tried to write. - **Typical trigger:** Only for read-only API keys, on any POST, PUT, PATCH or DELETE operation. - **Fix:** Use a key with write permission for this call. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). #### [session_required](https://upfour.io/docs/api/errors#code-session_required) The operation is available only to a signed-in browser session, not to an API key. - **Typical trigger:** Only for API keys, on routes that manage keys or are limited to the web app. - **Fix:** Do this in the app while signed in; API keys cannot call it. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). ### 404 Not found #### [design_template_not_found](https://upfour.io/docs/api/errors#code-design_template_not_found) The design template does not exist or is not visible to the caller. - **Typical trigger:** A design template id in the path or body that is unknown or not visible to the caller. - **Fix:** List design templates and use an id from the list. - **Operations:** 12 operations - [POST /client-templates](https://upfour.io/docs/api/client-templates#post_client_templates) - [PUT /client-templates/{templateID}](https://upfour.io/docs/api/client-templates#put_client_templates_templateID) - [POST /client-templates/{templateID}/dry-run](https://upfour.io/docs/api/client-templates#post_client_templates_templateID_dry_run) - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [GET /status-page-design-templates](https://upfour.io/docs/api/status-page-design-templates#get_status_page_design_templates) - [POST /status-page-design-templates](https://upfour.io/docs/api/status-page-design-templates#post_status_page_design_templates) - [GET /status-page-design-templates/{templateID}](https://upfour.io/docs/api/status-page-design-templates#get_status_page_design_templates_templateID) - [PUT /status-page-design-templates/{templateID}](https://upfour.io/docs/api/status-page-design-templates#put_status_page_design_templates_templateID) - [DELETE /status-page-design-templates/{templateID}](https://upfour.io/docs/api/status-page-design-templates#delete_status_page_design_templates_templateID) - [GET /status-page-design-templates/{templateID}/assets/{kind}](https://upfour.io/docs/api/status-page-design-templates#get_status_page_design_templates_templateID_assets_kind) - [POST /status-pages](https://upfour.io/docs/api/status-pages#post_status_pages) - [PUT /status-pages/{pageID}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID) #### [not_found](https://upfour.io/docs/api/errors#code-not_found) The resource does not exist or is outside the caller's scope. - **Typical trigger:** An id in the path that is unknown, belongs to another Company, or lies outside the key's client scope, and a client-portal session asking for a route the portal does not expose. - **Fix:** Check the id and that the key's client scope covers it; do not retry an unchanged request. - **Operations:** Under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation), and from handlers on 196 of 271 operations. ### 409 Conflict #### [channel_in_use](https://upfour.io/docs/api/errors#code-channel_in_use) The alert channel is still used by monitors or alert plans, so it was not deleted. - **Typical trigger:** Deleting an alert channel that a monitor notifies or an alert plan step targets. \`details\` carries the counts \`monitors\` and \`alert_plans\`. - **Fix:** Remove the channel from those monitors and alert plan steps first, then delete it. - **Operations:** - [DELETE /notification_channels/{channelID}](https://upfour.io/docs/api/notification-channels#delete_notification_channels_channelID) #### [conflict](https://upfour.io/docs/api/errors#code-conflict) The request conflicts with the current state of the resource. - **Typical trigger:** Creating something that already exists, or acting on a resource whose state no longer allows it, such as a postmortem for an incident that is not resolved. - **Fix:** Fetch the current state, resolve the difference and send the request again. - **Operations:** 11 operations - [GET /incidents/{incidentID}/ai](https://upfour.io/docs/api/incidents#get_incidents_incidentID_ai) - [POST /incidents/{incidentID}/ai/postmortem](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_postmortem) - [POST /incidents/{incidentID}/ai/summary](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_summary) - [PUT /incidents/{incidentID}/ai/{kind}/rating](https://upfour.io/docs/api/incidents#put_incidents_incidentID_ai_kind_rating) - [POST /invites](https://upfour.io/docs/api/invites#post_invites) - [POST /monitors/batch](https://upfour.io/docs/api/monitors#post_monitors_batch) - [POST /organization](https://upfour.io/docs/api/organization#post_organization) - [PUT /organization/ai-quota](https://upfour.io/docs/api/organization#put_organization_ai_quota) - [GET /organization/ai-usage](https://upfour.io/docs/api/organization#get_organization_ai_usage) - [POST /reports/{runID}/share](https://upfour.io/docs/api/reports#post_reports_runID_share) - [DELETE /status-pages/{pageID}/updates/{updateID}](https://upfour.io/docs/api/status-pages#delete_status_pages_pageID_updates_updateID) #### [design_template_conflict](https://upfour.io/docs/api/errors#code-design_template_conflict) The design template was changed after the caller read it. - **Typical trigger:** Updating or applying a design template that was changed after the caller read it. - **Fix:** Reload the template and apply the change again. - **Operations:** 10 operations - [POST /client-templates/{templateID}/dry-run](https://upfour.io/docs/api/client-templates#post_client_templates_templateID_dry_run) - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [GET /status-page-design-templates](https://upfour.io/docs/api/status-page-design-templates#get_status_page_design_templates) - [POST /status-page-design-templates](https://upfour.io/docs/api/status-page-design-templates#post_status_page_design_templates) - [GET /status-page-design-templates/{templateID}](https://upfour.io/docs/api/status-page-design-templates#get_status_page_design_templates_templateID) - [PUT /status-page-design-templates/{templateID}](https://upfour.io/docs/api/status-page-design-templates#put_status_page_design_templates_templateID) - [DELETE /status-page-design-templates/{templateID}](https://upfour.io/docs/api/status-page-design-templates#delete_status_page_design_templates_templateID) - [GET /status-page-design-templates/{templateID}/assets/{kind}](https://upfour.io/docs/api/status-page-design-templates#get_status_page_design_templates_templateID_assets_kind) - [POST /status-pages](https://upfour.io/docs/api/status-pages#post_status_pages) - [PUT /status-pages/{pageID}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID) #### [domain_claimed](https://upfour.io/docs/api/errors#code-domain_claimed) The domain is in use by another Company. - **Typical trigger:** Setting a custom domain on a status page when another Company already holds it; details.domain names it. - **Fix:** Prove control of the domain with the TXT record shown for the page, or use a different domain. - **Operations:** - [PUT /status-pages/{pageID}/custom-domain](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_custom_domain) #### [domain_move_stale](https://upfour.io/docs/api/errors#code-domain_move_stale) The page named as the domain's current holder is not the holder any more. - **Typical trigger:** Moving a domain with move_from_page_id set to a page that does not hold it; details.page names the real holder. - **Fix:** Read the domain's current holder and send the move again with that page. - **Operations:** - [PUT /status-pages/{pageID}/custom-domain](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_custom_domain) #### [domain_on_other_page](https://upfour.io/docs/api/errors#code-domain_on_other_page) The domain is used by another status page in the same Company. - **Typical trigger:** Setting a custom domain that another page of the Company already holds; details.page names that page. - **Fix:** Move the domain on purpose by sending the holder's page id as the page to move from, or choose another domain. - **Operations:** - [PUT /status-pages/{pageID}/custom-domain](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_custom_domain) #### [domain_removal_pending](https://upfour.io/docs/api/errors#code-domain_removal_pending) The domain is still being disconnected from its previous status page. - **Typical trigger:** Setting a domain right after it was removed from another page, before the disconnect finished. - **Fix:** Try again in a few minutes. - **Operations:** - [PUT /status-pages/{pageID}/custom-domain](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_custom_domain) #### [domain_used_in_company](https://upfour.io/docs/api/errors#code-domain_used_in_company) The domain is used by a status page in the Company that the caller cannot see. - **Typical trigger:** Setting a custom domain held by a page outside the caller's client scope; the page is not named. - **Fix:** Ask someone with access to that page to move or remove the domain, or choose another domain. - **Operations:** - [PUT /status-pages/{pageID}/custom-domain](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_custom_domain) #### [idempotency_key_conflict](https://upfour.io/docs/api/errors#code-idempotency_key_conflict) The Idempotency-Key was already used with a different request body. - **Typical trigger:** Only on POST and PATCH requests with an Idempotency-Key header that repeat a stored key with a changed body; details.original_request_at gives the first request's time. - **Fix:** Send the same body to replay the first answer, or use a new key for a new request. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). #### [idempotency_replay_unavailable](https://upfour.io/docs/api/errors#code-idempotency_replay_unavailable) The request was already processed, but its stored answer cannot be replayed. - **Typical trigger:** Only on POST and PATCH requests with an Idempotency-Key header whose stored response was made with a different API key, or under different scopes, access level or client access, or is no longer visible to the caller. - **Fix:** Read the resource's current state instead of replaying, and use a new key for any new attempt. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). #### [oncall_schedule_in_use](https://upfour.io/docs/api/errors#code-oncall_schedule_in_use) The on-call rotation is still a target of an alert plan step, so it was not deleted. - **Typical trigger:** Deleting an on-call rotation that an alert plan step targets as \`oncall:\`. \`details.alert_plans\` lists those plans. - **Fix:** Remove the rotation from the steps of those alert plans first, then delete it. - **Operations:** - [DELETE /oncall-schedules/{scheduleID}](https://upfour.io/docs/api/oncall-schedules#delete_oncall_schedules_scheduleID) #### [subscriber_import_running](https://upfour.io/docs/api/errors#code-subscriber_import_running) Another subscriber import of this Company is still running. - **Typical trigger:** Starting an import while a previous one has not finished. - **Fix:** Wait for the running import to finish, then start the next. - **Operations:** - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) ### 413 Content too large #### [attachment_too_large](https://upfour.io/docs/api/errors#code-attachment_too_large) The attachment is over the size limit. - **Typical trigger:** Uploading an incident attachment larger than the limit; details.max_bytes gives it. - **Fix:** Compress or split the file below details.max_bytes. - **Operations:** - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) #### [file_too_large](https://upfour.io/docs/api/errors#code-file_too_large) The uploaded file is over the size limit. - **Typical trigger:** Uploading a logo or image larger than details.max_bytes. - **Fix:** Reduce the file size and upload again. - **Operations:** - [POST /clients](https://upfour.io/docs/api/clients#post_clients) - [PUT /clients/{clientID}](https://upfour.io/docs/api/clients#put_clients_clientID) - [GET /organization/report-branding](https://upfour.io/docs/api/organization#get_organization_report_branding) - [PUT /organization/report-branding](https://upfour.io/docs/api/organization#put_organization_report_branding) - [PUT /status-pages/{pageID}/assets/{kind}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_assets_kind) #### [import_too_large](https://upfour.io/docs/api/errors#code-import_too_large) The import body is over the size limit. - **Typical trigger:** A batch monitor import larger than details.max_bytes. - **Fix:** Split the import into several requests. - **Operations:** - [POST /monitors/batch](https://upfour.io/docs/api/monitors#post_monitors_batch) - [POST /monitors/batch/dry-run](https://upfour.io/docs/api/monitors#post_monitors_batch_dry_run) #### [subscriber_import_too_large](https://upfour.io/docs/api/errors#code-subscriber_import_too_large) The subscriber file is over the size limit. - **Typical trigger:** Uploading a subscriber file larger than details.max_bytes. - **Fix:** Split the file into smaller ones. - **Operations:** - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) ### 422 Unprocessable content #### [ai_budget_above_platform_limit](https://upfour.io/docs/api/errors#code-ai_budget_above_platform_limit) The monthly AI budget is above the platform limit. - **Typical trigger:** Saving an AI budget larger than the platform allows; details.limit gives the maximum. - **Fix:** Set a budget at or below details.limit. - **Operations:** - [GET /incidents/{incidentID}/ai](https://upfour.io/docs/api/incidents#get_incidents_incidentID_ai) - [POST /incidents/{incidentID}/ai/postmortem](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_postmortem) - [POST /incidents/{incidentID}/ai/summary](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_summary) - [PUT /incidents/{incidentID}/ai/{kind}/rating](https://upfour.io/docs/api/incidents#put_incidents_incidentID_ai_kind_rating) - [PUT /organization/ai-quota](https://upfour.io/docs/api/organization#put_organization_ai_quota) - [GET /organization/ai-usage](https://upfour.io/docs/api/organization#get_organization_ai_usage) #### [ai_call_cap_above_platform_limit](https://upfour.io/docs/api/errors#code-ai_call_cap_above_platform_limit) The monthly AI call cap is above the platform limit. - **Typical trigger:** Saving an AI call cap larger than the platform allows; details.limit gives the maximum. - **Fix:** Set a cap at or below details.limit. - **Operations:** - [GET /incidents/{incidentID}/ai](https://upfour.io/docs/api/incidents#get_incidents_incidentID_ai) - [POST /incidents/{incidentID}/ai/postmortem](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_postmortem) - [POST /incidents/{incidentID}/ai/summary](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_summary) - [PUT /incidents/{incidentID}/ai/{kind}/rating](https://upfour.io/docs/api/incidents#put_incidents_incidentID_ai_kind_rating) - [PUT /organization/ai-quota](https://upfour.io/docs/api/organization#put_organization_ai_quota) - [GET /organization/ai-usage](https://upfour.io/docs/api/organization#get_organization_ai_usage) #### [provider_auth_rejected](https://upfour.io/docs/api/errors#code-provider_auth_rejected) The alert channel's provider rejected the credentials. - **Typical trigger:** A test alert whose provider answered 401 or 403. - **Fix:** Check the token, secret or account details of the channel. - **Operations:** - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) #### [provider_rejected](https://upfour.io/docs/api/errors#code-provider_rejected) The alert channel's provider rejected the test. - **Typical trigger:** A test alert whose provider answered 400, 404, 405, 410 or 422. - **Fix:** Check the channel's address and settings. - **Operations:** - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) #### [provider_unreachable](https://upfour.io/docs/api/errors#code-provider_unreachable) The alert channel's address cannot be reached. - **Typical trigger:** A test alert to a host that does not resolve, refuses the connection, has an invalid URL or an invalid HTTPS certificate. - **Fix:** Check the URL and its HTTPS certificate. - **Operations:** - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) #### [subscriber_confirmations_full](https://upfour.io/docs/api/errors#code-subscriber_confirmations_full) Too many addresses are waiting for confirmation. - **Typical trigger:** An import or sign-up that would exceed the number of unconfirmed addresses allowed; nothing was added, details gives new_addresses and free_places. - **Fix:** Wait for confirmations or remove unconfirmed addresses, then add fewer addresses. - **Operations:** - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) #### [subscriber_import_too_many_rows](https://upfour.io/docs/api/errors#code-subscriber_import_too_many_rows) The subscriber import has too many rows. - **Typical trigger:** An import with more rows than details.max_rows; nothing was imported. - **Fix:** Split the import into several files. - **Operations:** - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) ### 429 Too many requests #### [confirmation_rate_limited](https://upfour.io/docs/api/errors#code-confirmation_rate_limited) Subscriber confirmation emails are being sent faster than the limits allow. - **Typical trigger:** Adding subscribers faster than the confirmation limits allow; details.reason says which limit, and details.retry_at and Retry-After say when to try again. - **Fix:** Wait until details.retry_at, then add the remaining addresses. - **Operations:** - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) #### [rate_limit_exceeded](https://upfour.io/docs/api/errors#code-rate_limit_exceeded) Too many requests in a short time. - **Typical trigger:** The per-client or per-credential request limit was reached, or an endpoint with its own limit, such as test checks or AI calls, refused the call; Retry-After carries the wait in seconds where the code sets it. - **Fix:** Wait for Retry-After seconds, then retry with backoff and spread bursts over time. - **Operations:** Every operation, under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation). Handlers also return it on: - [GET /incidents/{incidentID}/ai](https://upfour.io/docs/api/incidents#get_incidents_incidentID_ai) - [POST /incidents/{incidentID}/ai/postmortem](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_postmortem) - [POST /incidents/{incidentID}/ai/summary](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_summary) - [PUT /incidents/{incidentID}/ai/{kind}/rating](https://upfour.io/docs/api/incidents#put_incidents_incidentID_ai_kind_rating) - [PUT /organization/ai-quota](https://upfour.io/docs/api/organization#put_organization_ai_quota) - [GET /organization/ai-usage](https://upfour.io/docs/api/organization#get_organization_ai_usage) ### 500 Internal server error #### [internal_error](https://upfour.io/docs/api/errors#code-internal_error) 500 · 502 The server failed while handling the request. - **Typical trigger:** An unexpected failure or a failed upstream call; the message of a 5xx is replaced by "Internal server error" except for 503 and a few provider failures, and the cause stays in the server log. - **Fix:** Retry with backoff, and send request_id to support if it keeps failing. - **Operations:** Under the condition in [Errors on every operation](https://upfour.io/docs/api/errors#every-operation), and from handlers on 118 of 271 operations. ### 502 Bad gateway #### [channel_test_failed](https://upfour.io/docs/api/errors#code-channel_test_failed) The alert channel's provider could not deliver the test. - **Typical trigger:** Sending a test alert to a channel when the provider fails in a way that fits none of the other provider codes. - **Fix:** Check the channel's address and settings, then test again. - **Operations:** - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) ### 503 Service unavailable #### [notification_setup_incomplete](https://upfour.io/docs/api/errors#code-notification_setup_incomplete) The Company's setup is incomplete, so the channel cannot be created. - **Typical trigger:** Creating an alert channel in a Company that has no default team. - **Fix:** Contact support with the request_id so the setup can be completed. - **Operations:** - [POST /notification_channels](https://upfour.io/docs/api/notification-channels#post_notification_channels) #### [quota_gate_unavailable](https://upfour.io/docs/api/errors#code-quota_gate_unavailable) The limit check itself failed, so the action was not carried out. - **Typical trigger:** The quota service could not decide while the request ran. - **Fix:** Retry in a moment; nothing was changed. - **Operations:** 21 operations - [POST /escalation-policies](https://upfour.io/docs/api/escalation-policies#post_escalation_policies) - [PUT /escalation-policies/{policyID}](https://upfour.io/docs/api/escalation-policies#put_escalation_policies_policyID) - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) - [POST /invites](https://upfour.io/docs/api/invites#post_invites) - [POST /invites/{inviteID}/resend](https://upfour.io/docs/api/invites#post_invites_inviteID_resend) - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) - [POST /reports/schedules](https://upfour.io/docs/api/reports#post_reports_schedules) - [PUT /reports/schedules/{scheduleID}](https://upfour.io/docs/api/reports#put_reports_schedules_scheduleID) - [POST /reports/schedules/{scheduleID}/run-now](https://upfour.io/docs/api/reports#post_reports_schedules_scheduleID_run_now) - [POST /reports/{runID}/share](https://upfour.io/docs/api/reports#post_reports_runID_share) - [POST /status-pages](https://upfour.io/docs/api/status-pages#post_status_pages) - [POST /status-pages/{pageID}/sections/{sectionID}/resources](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_sections_sectionID_resources) - [PUT /status-pages/{pageID}/sections/{sectionID}/resources/{resourceID}](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_sections_sectionID_resources_resourceID) - [PUT /status-pages/{pageID}/structure](https://upfour.io/docs/api/status-pages#put_status_pages_pageID_structure) - [POST /status-pages/{pageID}/subscribers](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers) - [POST /status-pages/{pageID}/subscribers/upload](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_upload) - [POST /status-pages/{pageID}/subscribers/{subscriberID}/resend](https://upfour.io/docs/api/status-pages#post_status_pages_pageID_subscribers_subscriberID_resend) - [POST /webhook-subscriptions](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions) - [POST /webhook-subscriptions/{subscriptionID}/redeliver/{deliveryID}](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions_subscriptionID_redeliver_deliveryID) - [POST /webhook-subscriptions/{subscriptionID}/test](https://upfour.io/docs/api/webhook-subscriptions#post_webhook_subscriptions_subscriptionID_test) #### [service_unavailable](https://upfour.io/docs/api/errors#code-service_unavailable) The service or a dependency the request needs cannot take it right now. - **Typical trigger:** A dependency such as the AI provider, the checkout or the report runner is not available; the action was not carried out. - **Fix:** Retry with backoff; nothing was changed by the failed request. - **Operations:** 10 operations - [GET /incidents/{incidentID}/ai](https://upfour.io/docs/api/incidents#get_incidents_incidentID_ai) - [POST /incidents/{incidentID}/ai/postmortem](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_postmortem) - [POST /incidents/{incidentID}/ai/summary](https://upfour.io/docs/api/incidents#post_incidents_incidentID_ai_summary) - [PUT /incidents/{incidentID}/ai/{kind}/rating](https://upfour.io/docs/api/incidents#put_incidents_incidentID_ai_kind_rating) - [POST /incidents/{incidentID}/attachments](https://upfour.io/docs/api/incidents#post_incidents_incidentID_attachments) - [POST /monitors/batch](https://upfour.io/docs/api/monitors#post_monitors_batch) - [PUT /organization/ai-quota](https://upfour.io/docs/api/organization#put_organization_ai_quota) - [GET /organization/ai-usage](https://upfour.io/docs/api/organization#get_organization_ai_usage) - [POST /reports/schedules/{scheduleID}/run-now](https://upfour.io/docs/api/reports#post_reports_schedules_scheduleID_run_now) - [POST /reports/{runID}/share](https://upfour.io/docs/api/reports#post_reports_runID_share) #### [test_unavailable](https://upfour.io/docs/api/errors#code-test_unavailable) Sending a test is not possible right now. - **Typical trigger:** A test alert request while the test sender cannot take it. - **Fix:** Try again in a moment. - **Operations:** - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) ### 504 Gateway timeout #### [provider_timeout](https://upfour.io/docs/api/errors#code-provider_timeout) The alert channel's provider did not answer in time. - **Typical trigger:** A test alert whose provider took too long to respond. - **Fix:** Check the address and try again later. - **Operations:** - [POST /monitors/{monitorID}/test-alert](https://upfour.io/docs/api/monitors#post_monitors_monitorID_test_alert) - [POST /notification_channels/{channelID}/test](https://upfour.io/docs/api/notification-channels#post_notification_channels_channelID_test) ## Codes of the web app The routes behind these 40 codes are not part of the public API: sign-in, billing, add-ons, support messages and test checks. API keys do not reach them, and nothing here is promised to stay. They are listed so that a code you find in a log or in the app has an explanation. #### [account_deletion_invalid_password](https://upfour.io/docs/api/errors#code-account_deletion_invalid_password) 400 The password given to confirm the account deletion is wrong. - **Typical trigger:** Deleting the signed-in account with a current password that does not match. - **Fix:** Send the account's current password, or reset it first. #### [account_deletion_owner_transfer_required](https://upfour.io/docs/api/errors#code-account_deletion_owner_transfer_required) 409 The account owns a Company and must hand ownership over before it can be deleted. - **Typical trigger:** Deleting the account of a Company owner. - **Fix:** Transfer ownership to another member, or ask the up4 team to delete the whole Company. #### [account_deletion_unavailable](https://upfour.io/docs/api/errors#code-account_deletion_unavailable) 503 Account deletion cannot be carried out right now. - **Typical trigger:** A server-side failure while processing the deletion. - **Fix:** Email privacy@upfour.io so the up4 team can process it. #### [addon_change_open](https://upfour.io/docs/api/errors#code-addon_change_open) 409 An add-on purchase is still waiting for its payment, so the plan cannot change. - **Typical trigger:** Changing the plan while an earlier add-on purchase is open. - **Fix:** Finish or cancel the open add-on purchase, then change the plan. #### [addons_change_failed](https://upfour.io/docs/api/errors#code-addons_change_failed) 502 Stripe could not be reached for an add-on change; nothing was changed. - **Typical trigger:** Stripe failed or timed out while the add-on change was applied. - **Fix:** Retry in a few minutes; the change applies only when a request succeeds. #### [below_reduction_floor](https://upfour.io/docs/api/errors#code-below_reduction_floor) 422 The new pack quantity is lower than current use needs. - **Typical trigger:** Reducing an add-on to fewer packs than what the Company uses. - **Fix:** Choose a quantity at or above what is in use, or free up usage first. #### [billing_portal_failed](https://upfour.io/docs/api/errors#code-billing_portal_failed) 502 The billing portal could not be opened. - **Typical trigger:** Stripe failed or timed out while the portal session was created; the plan and payment details are unchanged. - **Fix:** Retry in a few minutes, or message the up4 team. #### [checker_busy](https://upfour.io/docs/api/errors#code-checker_busy) 503 The checkers are too busy for a test check. - **Typical trigger:** A test check while the checker pool or the target address is at its test limit. - **Fix:** Try again in a few seconds. #### [checker_unavailable](https://upfour.io/docs/api/errors#code-checker_unavailable) 503 The test check could not be started. - **Typical trigger:** A test check when the request cannot be sent to a checker. - **Fix:** Try again later. #### [checkout_failed](https://upfour.io/docs/api/errors#code-checkout_failed) 502 The checkout for the plan could not be opened. - **Typical trigger:** Stripe failed or timed out while the checkout session was created; nothing was charged. - **Fix:** Retry in a few minutes, or message the up4 team. #### [custom_domain_slots_retired](https://upfour.io/docs/api/errors#code-custom_domain_slots_retired) 410 Custom domain slots are no longer sold. - **Typical trigger:** Buying or changing a custom domain slot; a connected custom domain is billed per day from the credit. - **Fix:** Connect the domain to a status page directly. #### [idempotency_key_required](https://upfour.io/docs/api/errors#code-idempotency_key_required) 400 The request needs an Idempotency-Key header. - **Typical trigger:** An add-on or support request sent without Idempotency-Key. - **Fix:** Send a unique Idempotency-Key header and keep it for retries. #### [invalid_code](https://upfour.io/docs/api/errors#code-invalid_code) 401 The two-factor code did not match. - **Typical trigger:** Confirming two-factor setup at sign-in with a wrong or expired code. - **Fix:** Check the time on the phone and enter the current code. #### [invalid_quantities](https://upfour.io/docs/api/errors#code-invalid_quantities) 400 The add-on quantities are not valid. - **Typical trigger:** Changing add-ons with no quantity, an unknown add-on, a quantity outside what can be booked, or a change that alters nothing; details names the reason. - **Fix:** Send quantities within the allowed range and at least one that differs from the current one. #### [invalid_signature](https://upfour.io/docs/api/errors#code-invalid_signature) 401 The heartbeat ping's signature is not valid. - **Typical trigger:** Pinging a scheduled job that requires signed pings with a missing or wrong X-Up4-Signature header. - **Fix:** Sign the ping as documented for the job. #### [invite_organization_conflict](https://upfour.io/docs/api/errors#code-invite_organization_conflict) 409 The account already belongs to another Company. - **Typical trigger:** Accepting an invite, signing in through SSO or verifying a magic link with an account that is a member of a different Company. - **Fix:** Use a different email address, or leave the other Company first. #### [no_live_region](https://upfour.io/docs/api/errors#code-no_live_region) 503 No checker is online in the selected region. - **Typical trigger:** A test check for a region with no live checker. - **Fix:** Try again in a minute or select another region. #### [no_pending](https://upfour.io/docs/api/errors#code-no_pending) 404 No add-on purchase is waiting for its payment. - **Typical trigger:** Cancelling a pending purchase when none is open. - **Fix:** Refresh the add-on state; there is nothing to cancel. #### [not_purchasable](https://upfour.io/docs/api/errors#code-not_purchasable) 409 The add-on cannot be bought or changed in the current state. - **Typical trigger:** A purchase or plan change when an add-on has no price, the Company is read-only or another condition applies; details.reason names it. - **Fix:** Act on details.reason, or message the up4 team. #### [nothing_scheduled](https://upfour.io/docs/api/errors#code-nothing_scheduled) 404 No reduction is scheduled for the add-on. - **Typical trigger:** Withdrawing a scheduled reduction when none exists for that add-on. - **Fix:** Refresh the add-on state; there is nothing to withdraw. #### [password_required](https://upfour.io/docs/api/errors#code-password_required) 409 The account has no password yet. - **Typical trigger:** Starting two-factor setup at sign-in for an account without a password. - **Fix:** Use Forgot password to set one, sign in again and then set up two-factor. #### [payment_pending](https://upfour.io/docs/api/errors#code-payment_pending) 409 A change to the subscription is still waiting for its payment. - **Typical trigger:** Changing the plan while the subscription has an unpaid pending update. - **Fix:** Finish the pending payment, then change the plan. #### [pending_lapses](https://upfour.io/docs/api/errors#code-pending_lapses) 409 The pending purchase cannot be cancelled and lapses on its own. - **Typical trigger:** Cancelling a purchase that is not paid yet. - **Fix:** Wait for it to lapse if it is not paid. #### [pending_open](https://upfour.io/docs/api/errors#code-pending_open) 409 An add-on purchase is still waiting for its payment. - **Typical trigger:** Starting, confirming or changing an add-on purchase while an earlier one is open. - **Fix:** Finish or let the open purchase lapse before starting another. #### [price_unavailable](https://upfour.io/docs/api/errors#code-price_unavailable) 503 The price for the monitor is currently unavailable. - **Typical trigger:** Reading a monitor's month-to-date cost while a meter price is missing; the API never answers 0 for a missing price. - **Fix:** Try again later. #### [probe_timeout](https://upfour.io/docs/api/errors#code-probe_timeout) 504 No checker answered the test check in time. - **Typical trigger:** A test check that got no reply before its deadline. - **Fix:** Try again; if it keeps failing, check the target and region. #### [quote_expired](https://upfour.io/docs/api/errors#code-quote_expired) 409 The add-on price is no longer valid. - **Typical trigger:** Confirming a quote after its price expired. - **Fix:** Review the change again to get a new quote. #### [quote_not_found](https://upfour.io/docs/api/errors#code-quote_not_found) 404 The add-on quote does not exist. - **Typical trigger:** Confirming a quote id that is unknown. - **Fix:** Request a new quote and confirm that one. #### [subscription_change_failed](https://upfour.io/docs/api/errors#code-subscription_change_failed) 502 Stripe could not be reached for the subscription change; nothing was applied. - **Typical trigger:** Stripe failed or timed out while the plan change was applied. - **Fix:** Retry in a few minutes, or message the up4 team. #### [subscriptions_unavailable](https://upfour.io/docs/api/errors#code-subscriptions_unavailable) 409 New status page subscriptions are not possible right now. - **Typical trigger:** A visitor signing up or confirming while the Company's subscriber pool is full. - **Fix:** Try again later. #### [support_category_not_available](https://upfour.io/docs/api/errors#code-support_category_not_available) 403 The message category is not available to this user. - **Typical trigger:** A client-portal user sending a message other than a problem report. - **Fix:** Choose the problem report category. #### [support_delivery_failed](https://upfour.io/docs/api/errors#code-support_delivery_failed) 503 The support message could not be delivered. - **Typical trigger:** The mail send failed after the request was accepted. - **Fix:** Email the support address named in the message directly. #### [support_messages_disabled](https://upfour.io/docs/api/errors#code-support_messages_disabled) 503 In-app support messages are switched off. - **Typical trigger:** Sending a support message while the feature is disabled. - **Fix:** Email the support address named in the message directly. #### [support_scope_invalid](https://upfour.io/docs/api/errors#code-support_scope_invalid) 400 The message scope is not valid. - **Typical trigger:** Sending a support message that refers to a scope the sender cannot use. - **Fix:** Pick a scope the sender can access, or send the message without one. #### [terms_not_accepted](https://upfour.io/docs/api/errors#code-terms_not_accepted) 400 The request does not accept the current terms of service. - **Typical trigger:** Signing up, starting a plan checkout or topping up the wallet without \`accept_terms: true\` and a \`terms_version\`. - **Fix:** Show the terms to the person, then send \`accept_terms: true\` with the current \`terms_version\`. #### [terms_notice_not_due](https://upfour.io/docs/api/errors#code-terms_notice_not_due) 409 The current terms version cannot be announced any more. - **Typical trigger:** An operator sends the change notice for a version whose effective date is today or in the past. - **Fix:** Publish a new version with a future effective date first (docs/ops/terms-versions.md). #### [terms_version_outdated](https://upfour.io/docs/api/errors#code-terms_version_outdated) 409 The terms version the request accepts is not the current one. - **Typical trigger:** A \`terms_version\` from a page loaded before a new version of the terms of service was published. - **Fix:** Reload the page, show the current terms and send their version. #### [topup_failed](https://upfour.io/docs/api/errors#code-topup_failed) 502 The payment page for the top-up could not be opened. - **Typical trigger:** Stripe failed or timed out while the top-up was prepared; nothing was charged. - **Fix:** Retry in a few minutes, or message the up4 team. #### [two_factor_already_enabled](https://upfour.io/docs/api/errors#code-two_factor_already_enabled) 409 Two-factor authentication is already on for the account. - **Typical trigger:** Starting two-factor setup for an account that already has it. - **Fix:** Sign in again. #### [two_factor_setup_expired](https://upfour.io/docs/api/errors#code-two_factor_setup_expired) 401 The two-factor setup step has expired. - **Typical trigger:** Continuing two-factor setup after its short window ended. - **Fix:** Sign in again to restart the setup.