Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt

Use this file to discover all available pages before exploring further.

The Scaling 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 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 team can locate the relevant logs.

​
Error types

TypeHTTP statusWhen it occurs
not_authorized_error401The Authorization header is missing or the API key is invalid or expired.
invalid_request_error400, 404, 409The 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_error422The request body or path parameter failed schema validation (wrong type, missing required field, out-of-range value, etc.).
internal_error500An unexpected error occurred on the server.

​
Error codes

CodeHTTP statusMeaning
missing_authorization_header401No Authorization header was provided.
invalid_api_key401The API key in the Authorization header is invalid or has expired.
not_found404The requested resource does not exist or is not accessible to your organization.
name_conflict409A resource with the same name already exists in your organization.
invalid_status_transition400The requested incident status transition is not permitted from the current status.
policy_in_use400The escalation policy cannot be deleted because it is attached to one or more active incidents.
invalid_participant400One or more participant IDs in the request are not members of your organization.
invalid_target400The referenced schedule does not exist in your organization.
invalid_timezone400The provided timezone string is not a valid IANA timezone identifier (e.g. America/New_York).
cannot_remove_self400An admin attempted to remove themselves from the organization.
cannot_change_own_role400An admin attempted to change their own role.

​
HTTP status codes

StatusMeaning
200The request succeeded.
400Bad request — the request violated a business rule. Check the code field for the specific reason.
401Unauthorized — the API key is missing or invalid.
404Not found — the resource does not exist or is not visible to your organization.
409Conflict — a resource with the same unique identifier (e.g. name) already exists.
422Unprocessable entity — the request body failed schema validation.
500Internal server error — something went wrong on the Scaling 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"
}