## Delete a server

`DELETE /v1/infra/servers/:id`

Deletes a server irreversibly: the virtual machine is destroyed at the provider, the database record is marked as `DELETED`, and open billing transactions are finalized. A deleted server cannot be recovered — create a new one via [`POST /v1/infra/servers`](./create.md). Deletion is idempotent only for the virtual machine on the provider side: if it has already been deleted there, no error is returned. A repeated call for a server that is already marked deleted returns 404.

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | Server ID from [`POST /v1/infra/servers`](./create.md) or [`GET /v1/infra/servers`](./list.md) |

## Examples

### curl — personal key

```bash
curl -X DELETE -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/db008c84-91a5-4e15-b9d5-6c6aa2838448
```

### curl — OAuth application

```bash
curl -X DELETE -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID
```

### JavaScript — personal key

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}`,
  {
    method: 'DELETE',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success } = await res.json()
if (success) console.log('Server deleted')
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}`,
  {
    method: 'DELETE',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on successful deletion |

The response is short — the body `{ "success": true }` confirms the deletion. No additional data is returned.

## Response example

```json
{
  "success": true
}
```

## Error response example

404 — the server is already deleted or does not exist:

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid or expired API key |
| 404 | `NOT_FOUND` | Server not found, belongs to another API key, or was already deleted |
| 409 | `GALAXY_HAS_APPS` | The server is a Galaxy host that still has non-deleted applications. Delete the applications first, then the host. The body contains `appCount` |
| 502 | `GALAXY_HOST_UNREACHABLE` | A Galaxy application: its host is unreachable and could not be woken. The response carries `error.hint` with a recovery plan — see "Known specifics" |
| 429 | `RATE_LIMITED` | The platform's overall request limit was exceeded |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **Handling 404 on retries is normal.** If the client lost the connection after the first `DELETE`, a retry will return 404. Catch 404 as "already deleted".
- **If the virtual machine has already been deleted at the provider by another means** (the provider's panel, manual cleanup) — `DELETE` still succeeds and marks the database record as deleted.
- **The quota is freed immediately.** After deletion you can create a new server right away — `MAX_SERVERS_REACHED` will no longer count this record.
- **Deletion works for any status.** Servers in `provisioning`, `running`, `sleeping`, and `error` are all deleted normally.
- **A Galaxy application is deleted by this same method.** When a Bitrix24 account places applications in galaxies (several applications run as containers on a shared host), `DELETE /v1/infra/servers/:id` removes the application the key owns: it tears down its container on the host and marks the record deleted. The response is `200 { "success": true }`, the same as for a regular server.
- **The platform wakes a sleeping Galaxy host on its own.** If the host of a Galaxy application is asleep, the platform wakes it before tearing down the container — there is no need to wake another application and retry the request. The error 502 `GALAXY_HOST_UNREACHABLE` remains only when the host is unreachable or could not be woken, for example when it is frozen for billing. In that case retry the request shortly.
- **The `502 GALAXY_HOST_UNREACHABLE` response has an `error.hint` field with a recovery plan.** It is an object of four strings: `reason` — why the host is unreachable right now, `recovery` — what to do, `recoveryAction` — the concrete call to retry, `note` — a caveat that the host status in the listing can lag behind the real tunnel state. The point of the hint: the server record is preserved until the container teardown actually runs on the host, so retrying the request in 1–2 minutes loses nothing. If the condition holds beyond 15 minutes, the host is genuinely down.
- **A Galaxy host with non-deleted applications is not deleted by this method.** If the server is a Galaxy host that still has non-deleted applications, the request returns 409 `GALAXY_HAS_APPS` with an `appCount` field. Delete the host's applications first, then the host itself.

## See also

- [Create a server](./create.md) — `POST /v1/infra/servers`.
- [List servers](./list.md) — `GET /v1/infra/servers` (deleted ones are not included in the output).
- [Get a server](./get.md) — `GET /v1/infra/servers/:id`.
- [Stop a server](/docs/infra/lifecycle/stop) — an alternative to deletion, if you want to return to the server later.
- [Put a server to sleep](/docs/infra/lifecycle/sleep-now) — to save money on a temporarily unused BLACKHOLE server.