## Проверить ключ провайдера

`POST /v1/ai/credentials/:id/test`

Перепроверяет сохранённый ключ у провайдера. Ничего не изменяет в самих учётных данных, но обновляет поля `lastError` и `lastErrorAt` ключа в зависимости от результата. Используйте, когда подозреваете, что ключ просрочен или у провайдера сменился API.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `id` (path) | string | да | ID ключа из [`GET /v1/ai/credentials`](./list.md) |

## Примеры

### curl — личный ключ

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/ai/credentials/cred_abc123def456/test \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/ai/credentials/cred_abc123def456/test \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const id = 'cred_abc123def456'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/ai/credentials/${id}/test`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log(data.valid ? 'Ключ корректен' : `Ошибка: ${data.error}`)
```

### JavaScript — OAuth-приложение

```javascript
const id = 'cred_abc123def456'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/ai/credentials/${id}/test`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
if (!data.valid) alert(`Ключ некорректен: ${data.error}`)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` (даже при некорректном ключе — это не ошибка эндпоинта) |
| `data.valid` | boolean | `true` — ключ принят провайдером; `false` — отвергнут |
| `data.error` | string | Сообщение об ошибке от провайдера, если `valid: false`. URL заменены на `[URL]`, длина обрезана до 200 символов |

## Пример ответа

Ключ корректен:

```json
{
  "success": true,
  "data": {
    "valid": true
  }
}
```

Ключ отвергнут провайдером:

```json
{
  "success": true,
  "data": {
    "valid": false,
    "error": "OpenAI API 401: Incorrect API key provided"
  }
}
```

## Пример ответа при ошибке

`404 not_found` — ключ не найден или принадлежит другому пользователю:

```json
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 404 | `not_found` | Ключ с таким `id` не найден или не принадлежит вам |
| 400 | `no_key` | В сохранённых учётных данных нет поля `apiKey` (битый старый ключ) |
| 500 | `decryption_error` | Не удалось расшифровать сохранённые учётные данные |
| 422 | `provider_geoblocked` | Провайдер отклонил проверку ключа по региону нашего сервера. Подключите свой прокси или перейдите на OpenRouter. Ответ несёт поле `suggestions` |
| 403 | `scope_missing` | API-ключу не хватает скоупа `vibe:ai` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

Лимит проверок: 10 запросов в минуту (единый бакет на портал).

## Известные особенности

**Некорректный ключ — не ошибка эндпоинта.** Если провайдер отверг ключ — эндпоинт вернёт `200 OK` с `success: true` и `data.valid: false`. HTTP-ошибки (`4xx`/`5xx`) возвращаются только при проблемах с самим запросом (нет ключа, нет доступа, нечего расшифровать). Единственное исключение — региональная блокировка: провайдер отклонил проверку по региону нашего сервера, и эндпоинт отвечает `422 provider_geoblocked`.

**Запись результата в `lastError`.** Эндпоинт обновляет поля `lastError` и `lastErrorAt` ключа в базе. При успехе — обнуляет, при неудаче — записывает текст ошибки от провайдера. Эти поля видны в [`GET /v1/ai/credentials`](./list.md).

**Тайм-аут проверки — 10 секунд.** Если провайдер не отвечает за 10 секунд — `valid: false` с сообщением о тайм-ауте.

**Custom-провайдер проверяется по `baseUrl` ключа.** Для `custom-openai-compat` верификация идёт по тому `baseUrl`, который сохранён в учётных данных. Если у провайдера нет `GET /v1/models` — выполняется проверка через `POST /v1/chat/completions`.

## Смотрите также

- [Список ключей](./list.md)
- [Обновить ключ](./update.md)
- [Подключить ключ](./create.md)