Errors

The scaling.cloud API uses conventional HTTP status codes and returns a consistent JSON error body on every failure. Check the type field to understand the category of error, and the code field for the specific reason.

Error response shape

All error responses follow this structure:

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

statusCode

number

required

The HTTP status code for this response (e.g. 400, 401, 404, 422, 500).

type

string

required

The broad category of error. See the error types table below.

code

string

required

A machine-readable code that identifies the specific error within its type. See the error codes table below.

requestId

string

required

A UUID that uniquely identifies this request. Include this value when contacting scaling.cloud support.

Every response — including error responses — includes a requestId. If you open a support ticket, include the requestId from the failing response so the scaling.cloud team can locate the relevant logs.

Error types

Type	HTTP status	When it occurs
`not_authorized_error`	`401`	The `Authorization` header is missing or the API key is invalid or expired.
`invalid_request_error`	`400`, `404`, `409`	The request is well-formed but violates a business rule — for example, referencing a resource that does not exist, or conflicting with an existing name.
`validation_error`	`422`	The request body or path parameter failed schema validation (wrong type, missing required field, out-of-range value, etc.).
`internal_error`	`500`	An unexpected error occurred on the server.

Error codes

Code	HTTP status	Meaning
`missing_authorization_header`	`401`	No `Authorization` header was provided.
`invalid_api_key`	`401`	The API key in the `Authorization` header is invalid or has expired.
`not_found`	`404`	The requested resource does not exist or is not accessible to your organization.
`name_conflict`	`409`	A resource with the same name already exists in your organization.
`invalid_status_transition`	`400`	The requested incident status transition is not permitted from the current status.
`policy_in_use`	`400`	The escalation policy cannot be deleted because it is attached to one or more active incidents.
`invalid_participant`	`400`	One or more participant IDs in the request are not members of your organization.
`invalid_target`	`400`	The referenced schedule does not exist in your organization.
`invalid_timezone`	`400`	The provided timezone string is not a valid IANA timezone identifier (e.g. `America/New_York`).
`cannot_remove_self`	`400`	An admin attempted to remove themselves from the organization.
`cannot_change_own_role`	`400`	An admin attempted to change their own role.

HTTP status codes

Status	Meaning
`200`	The request succeeded.
`400`	Bad request — the request violated a business rule. Check the `code` field for the specific reason.
`401`	Unauthorized — the API key is missing or invalid.
`404`	Not found — the resource does not exist or is not visible to your organization.
`409`	Conflict — a resource with the same unique identifier (e.g. name) already exists.
`422`	Unprocessable entity — the request body failed schema validation.
`500`	Internal server error — something went wrong on the scaling.cloud side.

Common error examples

401 — Missing or invalid API key

Returned when the Authorization header is absent or the key cannot be verified.

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "missing_authorization_header",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "invalid_api_key",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

See Authentication for how to correctly include your API key.

404 — Resource not found

Returned when you reference an ID that does not exist or does not belong to your organization.

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

422 — Validation error

Returned when the request body fails schema validation — for example, a missing required field or a value of the wrong type. The code field may be empty for validation errors; the type of validation_error is the primary signal.

{
  "statusCode": 422,
  "type": "validation_error",
  "code": "",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Overview

Incidents

On-call Schedules

Escalation Policies

Routing Policies

Working Hours

Team

Error response shape

Error types

Error codes

HTTP status codes

Common error examples

401 — Missing or invalid API key

404 — Resource not found

422 — Validation error

​Error response shape

​Error types

​Error codes

​HTTP status codes

​Common error examples

​401 — Missing or invalid API key

​404 — Resource not found

​422 — Validation error

Error response shape

Error types

Error codes

HTTP status codes

Common error examples

401 — Missing or invalid API key

404 — Resource not found

422 — Validation error