> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudblast.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error handling and status codes

# Error Handling

All errors follow a consistent format:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong."
  }
}
```

Validation errors include a `details` object with per-field messages:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "plan_id": ["The plan id field is required."],
      "template_slug": ["The template slug field is required."]
    }
  }
}
```

## HTTP Status Codes

| Status | Meaning                                                   |
| ------ | --------------------------------------------------------- |
| `200`  | Success                                                   |
| `201`  | Resource created                                          |
| `204`  | Success with no response body (delete operations)         |
| `400`  | Bad request — check the error message                     |
| `401`  | Unauthenticated — invalid or missing token                |
| `402`  | Payment required — overdue invoices                       |
| `403`  | Forbidden — account banned or IP not whitelisted          |
| `404`  | Resource not found                                        |
| `409`  | Conflict — server is in a state that prevents this action |
| `422`  | Validation error — check the `details` object             |
| `429`  | Rate limited — too many requests                          |
| `500`  | Internal server error                                     |

## Common Error Codes

### Authentication

| Code              | Description                            |
| ----------------- | -------------------------------------- |
| `UNAUTHENTICATED` | Missing `Authorization: Bearer` header |
| `INVALID_TOKEN`   | API token not found                    |
| `ACCOUNT_BANNED`  | Account is suspended                   |
| `IP_NOT_ALLOWED`  | Request IP not in whitelist            |

### Server Operations

| Code                      | Description                                              |
| ------------------------- | -------------------------------------------------------- |
| `SERVER_STATUS_CONFLICT`  | Server is busy (installing, restoring, etc.)             |
| `NO_AVAILABLE_NODE`       | No node has capacity + matching template + available IPs |
| `RESOURCE_LIMIT_EXCEEDED` | CPU or RAM limit reached                                 |
| `OVERDUE_INVOICE`         | Must pay overdue invoices first                          |
| `PLAN_UNAVAILABLE`        | Plan is hidden                                           |
| `PLAN_OUT_OF_STOCK`       | Plan stock is depleted                                   |
| `NEW_USERS_ONLY`          | Plan restricted to first-time users                      |
| `TEMPLATE_NOT_FOUND`      | Template slug not available on the server's node         |

### IP Operations

| Code                    | Description                                 |
| ----------------------- | ------------------------------------------- |
| `IP_LIMIT_REACHED`      | Account IP limit reached                    |
| `SERVER_IP_LIMIT`       | Per-server IP limit reached                 |
| `NO_IPS_AVAILABLE`      | No IPs available in the pool                |
| `CANNOT_REMOVE_PRIMARY` | Cannot remove the primary IPv4/IPv6         |
| `RATE_LIMITED`          | Too many IP add/remove operations this week |

### Security Groups

| Code               | Description                                     |
| ------------------ | ----------------------------------------------- |
| `HAS_SERVERS`      | Must detach all servers before deleting a group |
| `ALREADY_ATTACHED` | Server is already in this security group        |