> ## 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.
# Errors
> Error response format, types, codes, and HTTP status codes returned by the scaling.cloud API.
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:
```json theme={null}
{
"statusCode": 404,
"type": "invalid_request_error",
"code": "not_found",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
```
The HTTP status code for this response (e.g. `400`, `401`, `404`, `422`, `500`).
The broad category of error. See the [error types table](#error-types) below.
A machine-readable code that identifies the specific error within its type. See the [error codes table](#error-codes) below.
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](https://www.iana.org/time-zones) (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.
```json theme={null}
{
"statusCode": 401,
"type": "not_authorized_error",
"code": "missing_authorization_header",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
```
```json theme={null}
{
"statusCode": 401,
"type": "not_authorized_error",
"code": "invalid_api_key",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
```
See [Authentication](/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.
```json theme={null}
{
"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.
```json theme={null}
{
"statusCode": 422,
"type": "validation_error",
"code": "",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
```