## 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 registration that was already sent 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` | The registration result is not confirmed yet. Repeat the call after the number of seconds in the `Retry-After` header. If the response persists, contact support and provide `error.details.registrationRef` |
| 409 | `BOT_REGISTRATION_AMBIGUOUS` | The key started several unfinished registrations with this code. If the response persists, contact support and provide the bot code and the Bitrix24 account |
| 409 | pending reason code | The registration is waiting for reconciliation with Bitrix24, and the reason is in `error.code`. Repeat the call after the number of seconds in `Retry-After`: 5 seconds or the time until the next scheduled registration check. If the response persists, contact support and provide `error.details.registrationRef` when the response contains it |
| 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)