## Recover a bot registration

`POST /v1/bots/registrations/:code/recover`

Completes a bot registration whose result was not confirmed right away and returns the bot ID in the Bitrix24 account. Call it with the same key and the same bot code as the original registration.

The call is needed when [`POST /v1/bots`](/docs/bots/management/create) responded with `409 BOT_EFFECT_DESIRED_STATE_NOT_PROVED`: the registration request was sent, but its result has not been checked yet. No new bot is registered — Vibecode checks the previously submitted registration and completes the bot record.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `code` (path) | string | yes | Bot code — the value of the `code` field from the [`POST /v1/bots`](/docs/bots/management/create) request |

No request body is required.

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log(data) // { botId: 42, code: 'support_bot', recovered: true }
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `data.botId` | number | Bot ID in the Bitrix24 account — the same as `data.bots[].id` in [`GET /v1/bots`](/docs/bots/management/list) |
| `data.code` | string | Bot code from the request path |
| `data.recovered` | boolean | Always `true` |

## Response example

```json
{
  "success": true,
  "data": {
    "botId": 42,
    "code": "support_bot",
    "recovered": true
  }
}
```

## Error response example

404 — the key has no registration with this code:

```json
{
  "success": false,
  "error": {
    "code": "BOT_REGISTRATION_NOT_FOUND",
    "message": "No owned registration is available for recovery"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `CODE_REQUIRED` | The bot code in the path is empty |
| 404 | `BOT_REGISTRATION_NOT_FOUND` | The key has no registration with this code that can be completed. A call with a key or code other than the ones used at registration gets the same response |
| 409 | `BOT_REGISTRATION_RECOVERY_PENDING` | Registration confirmation or reconciliation is still pending. The `Retry-After` header gives the retry delay in seconds: the time until the next scheduled check (1 to 300 seconds), or 30 seconds otherwise. If the response persists, contact support and provide `error.details.registrationRef` when present |
| 409 | `BOT_UNAVAILABLE` | The registration state requires a fix by the platform, for example due to an incompatible OAuth policy or a change in application enrollment. There is no `Retry-After` header and retrying will not help. Contact support with `error.details.registrationRef` when present, otherwise the original bot code and Bitrix24 account |
| 403 | `SCOPE_DENIED` | The API key does not have the `imbot` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — see [access rights](/docs/access-rights) |

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

## Known specifics

**Repeating the call is safe.** If the registration is already completed, a call with the same key and code returns `200` with the same `botId` again.

## See also

- [List bots](/docs/bots/management/list)
- [Bot access recovery](/docs/bots/ownership-recovery)
- [Bot platform](/docs/bots)