# Вопросы и устранение неполадок

Проверьте свой доступ, исправьте неудавшийся запрос или найдите ответ об использовании FlashData.

Каноническая ссылка: https://flashdata.dev/ru/docs/guides/troubleshooting
Разработчик: 2026-11-04 by FlashData

- [Исправить ошибку](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#fix) — Команды и исправления по симптомам
- [Общие вопросы](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#faq) — Доступ, кредиты и данные

<a id="diagnose"></a>

## Начните с бесплатной проверки доступа

Проверь, где не получилось выполнить задание. Используйте его существующие учетные данные; эти команды не отправляют запрос.

### CLI

Используйте сохраненный доступ CLI. Для именованного профиля добавьте имя --profile к каждой команде. Эти чтения не тратят кредиты на запросы.

#### Бесплатный аккаунт читать

```bash
flashdata --version
flashdata doctor --offline
flashdata auth status --json
```

- [Настройка ключа](https://flashdata.dev/ru/docs/guides/api-keys-and-permissions/reference.md#store)

### Bash / cURL

Используйте существующий FLASHDATA_API_KEY в том же терминале, контейнере или запланированной работе. Требуется cURL 7.76+.

#### Прочитать аккаунт JSON

```bash
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  'https://api.flashdata.dev/v2/api-access/identity' || exit
printf '\n'
)
```


### PowerShell 7

Используйте существующий FLASHDATA_API_KEY в том же терминале, контейнере или запланированной работе.

#### Прочитать аккаунт JSON

```powershell
& {
  $ErrorActionPreference = 'Stop'
  if ([string]::IsNullOrWhiteSpace($env:FLASHDATA_API_KEY)) {
    throw 'Set FLASHDATA_API_KEY first'
  }
  $flashdataHeaders = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
  $flashdataBase = 'https://api.flashdata.dev/v2'
  $flashdataUri = "$flashdataBase/api-access/identity"
  Invoke-RestMethod -Uri $flashdataUri `
    -Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
    ConvertTo-Json -Depth 20
}
```


- [401 / 403: учетные данные](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#credentials)
- [402: кредиты](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#credits)
- [429: предел скорости](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#rate-limit)
- [400 / 422: запрос](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#request)
- [Отложенная или неудавшаяся работа](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#jobs)
- [Тайм-аут 5xx](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#uncertain)
- [Подключение MCP](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#mcp)

<a id="check-result"></a>

### Что проверить

Идентификатор должен иметь access: ready и включать ваш источник в объемы. В CLI JSON, идентификатор находится на data.identity.identity; также требуется data.accessVerified: true. Успешная команда с accessVerified: false не имеет проверенного доступа.

Для профиля CLI, добавьте имя --profile к каждой команде ниже. Держите оригинального пользователя --state-dir и OS. FLASHDATA_API_KEY переопределяет сохраненный ключ CLI; SDK и хосты MCP используют собственную конфигурацию учетных данных.


<a id="fix"></a>

## Найти и решить проблему

Откройте симптом, который соответствует вашей ошибке. Используйте IDs и квитанции от исходной задачи.


<a id="runtime"></a>

### Команда не найдена или профиль отсутствует

Нет исполняемого файла: установите релиз для своего OS/CPU и добавьте его каталог в PATH. Пропущенный профиль: используйте исходный пользователь OS и каталог состояния. Проверьте внутри планировщика или контейнера.

#### Bash

##### Найдите исполняемый

```bash
command -v flashdata
flashdata --version
flashdata doctor --offline
```


#### PowerShell

##### Найдите исполняемый

```powershell
Get-Command flashdata
flashdata --version
flashdata doctor --offline
```


- [Установка CLI](https://flashdata.dev/ru/docs/guides/flashdata-cli/reference.md#install)
- [Профили и государственные каталоги](https://flashdata.dev/ru/docs/guides/cli-automation/reference.md#profiles)

<a id="credentials"></a>

### 401 / 403: ключ, объем или срок действия

Чтобы заменить сохраненный ключ владельца, вставьте одобренный ключ в скрытую подсказку. Если FLASHDATA_API_KEY установлен, обновите этот секрет во время выполнения; сохранение другого ключа CLI не переопределит его.

1. 401: проверьте наличие просроченного, отозванного или неправильно настроенного ключа. 403: сравните запрашиваемый источник с областями идентификации.
2. REST и SDK используют X-API-Key. MCP OAuth не может заменить ключ API. Для временного доступа используйте восстановление претензии ниже.

#### Заменить и проверить сохраненный ключ владельца

```bash
flashdata auth login --replace
flashdata auth status --json
```

- [Ключевые разрешения и ротация](https://flashdata.dev/ru/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [Возвращение исков](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#claim)
- [MCP подключается](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#mcp)

<a id="claim"></a>

### Привязка одобрена, но агент всё ещё использует пробный доступ

Завершите передачу в том же профиле CLI, который создал претензию. Владелец завершает регистрацию, проверку электронной почты и согласие в браузере; CLI получает учетные данные.

#### Уже утверждено

##### Завершить и проверить

```bash
flashdata auth finish --wait --timeout 10m
flashdata auth status --json
```


#### Ссылка истекла

Запросите новую ссылку на существующую пробную версию, пусть владелец одобрит, а затем запустите auth finish. Не запускайте init снова.

##### Обновить ссылку на претензию

```bash
flashdata auth claim
```


- [Претензия и передача полномочий](https://flashdata.dev/ru/docs/guides/agent-onboarding/reference.md#help)
- [Проверяйте доступ владельца для повторяющихся задач](https://flashdata.dev/ru/docs/guides/recurring-tasks/reference.md)

<a id="credits"></a>

### 402: недостаточные кредиты

Сравните availableCredits с текущей ценой вашего источника. Привяжите исчерпанный пробный доступ к аккаунту, чтобы использовать баланс владельца, или попросите владельца проверить Billing перед повтором.

#### CLI

Используйте сохраненный доступ CLI. Для именованного профиля добавьте имя --profile к каждой команде. Эти чтения не тратят кредиты на запросы.

##### Бесплатный аккаунт читать

```bash
flashdata account balance
flashdata account pricing --source google_search --request-count 1
```

- [Настройка ключа](https://flashdata.dev/ru/docs/guides/api-keys-and-permissions/reference.md#store)

#### Bash / cURL

Используйте существующий FLASHDATA_API_KEY в том же терминале, контейнере или запланированной работе. Требуется cURL 7.76+.

##### Прочитать аккаунт JSON

```bash
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  'https://api.flashdata.dev/v2/api-access/balance' || exit
printf '\n'
curl --fail-with-body --silent --show-error --max-time 20 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  'https://api.flashdata.dev/v2/api-access/pricing?source=google_search&request_count=1' || exit
printf '\n'
)
```


#### PowerShell 7

Используйте существующий FLASHDATA_API_KEY в том же терминале, контейнере или запланированной работе.

##### Прочитать аккаунт JSON

```powershell
& {
  $ErrorActionPreference = 'Stop'
  if ([string]::IsNullOrWhiteSpace($env:FLASHDATA_API_KEY)) {
    throw 'Set FLASHDATA_API_KEY first'
  }
  $flashdataHeaders = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
  $flashdataBase = 'https://api.flashdata.dev/v2'
  $flashdataUri = "$flashdataBase/api-access/balance"
  Invoke-RestMethod -Uri $flashdataUri `
    -Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
    ConvertTo-Json -Depth 20
  $flashdataUri = "$flashdataBase/api-access/pricing?source=google_search&request_count=1"
  Invoke-RestMethod -Uri $flashdataUri `
    -Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
    ConvertTo-Json -Depth 20
}
```


- [Billing](https://flashdata.dev/app/billing)
- [Пробный доступ и привязка к аккаунту](https://flashdata.dev/ru/docs/guides/agent-onboarding/reference.md)
- [Цены на другие источники](https://flashdata.dev/ru/docs/guides/credits-and-billing/reference.md)

<a id="rate-limit"></a>

### 429: подождите до повторного запуска

Прочитайте Retry-After по неудавшейся реакции: секунды или дата HTTP. Подождите до этого и уменьшите параллелизм. Пробная регистрация позволяет три регистрации на IP-адрес в окне 24-час; повторно использовать исходный профиль и регистрационное доказательство.

Это бесплатное чтение демонстрирует сохранение заголовков, статуса и тела. Используйте Retry-After в случае неудачной операции; лимиты на запросы, регистрацию и чтение учетных записей могут отличаться.

#### Захват ответа · Bash / cURL / jq

```bash
# Bash + cURL + jq. This is a free account read.
(
test -n "$FLASHDATA_API_KEY" || { printf 'Set FLASHDATA_API_KEY first\n' >&2; exit 1; }
curl --silent --show-error --max-time 20 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --dump-header diagnostic-headers.txt --output diagnostic.json \
  --write-out '%{http_code}\n' \
  'https://api.flashdata.dev/v2/api-access/identity' > diagnostic-status.txt || exit
printf 'HTTP '; cat diagnostic-status.txt
awk 'tolower($1) == "retry-after:" {
  $1=""; sub(/^ /, ""); sub(/\r$/, ""); print "Retry-After: " $0
}' diagnostic-headers.txt
if jq -e 'type == "object"' diagnostic.json >/dev/null 2>&1; then
  jq '{access, scopes, status, code, requestId}
    | with_entries(select(.value != null))' diagnostic.json
else
  printf 'Non-JSON response saved in diagnostic.json; check the HTTP status.\n'
fi
)
```

#### Проверка способности счета

```bash
flashdata account limits
```

- [Ограничения ставок и обратный откат](https://flashdata.dev/ru/docs/guides/usage-and-limits/reference.md)

<a id="request"></a>

### 400 / 422: отказ ввода или обработки

Прочитайте код, детали и fieldErrors из ошибки HTTP. Исправьте тело запроса, сохраните его как request.json, а затем проверьте его. Держите Download учетные данные хранения в частном файле ввода. Если 422 исходит из результата существующей работы, сначала проверьте job.error.

#### Проверка без платного представления

```bash
flashdata query --input request.json --mode async --dry-run --json
```

- [Ссылки на исходный запрос](https://flashdata.dev/ru/docs/reference/reference.md)
- [Частная загрузка](https://flashdata.dev/ru/docs/guides/cli-automation/reference.md#storage)
- [Проверить существующую работу](https://flashdata.dev/ru/docs/guides/troubleshooting/reference.md#jobs)

<a id="jobs"></a>

### Работа в ожидании, или HTTP 200 с неудачной работой

Прочтите работу от submission.json, сохраненную квитанцию об асинхронизации. HTTP 200 означает успешное считывание статуса; job.status является результатом задачи (data.status в CLI JSON). Для Batch сохраните соответствующую запись из запросов как submission.json.

| Состояние или ошибка | Следующее действие |
| --- | --- |
| pending / processing | Подождите на той же работе, не подавайте ее снова. |
| completed | Сохраняйте и сохраняйте уже имеющийся результат. |
| failed | Проверить job.error перед отправкой исправленной работы. |
| 404 | Проверьте работу ID и отправку счета. |
| 409 | Результаты не готовы. Продолжайте проводить опросы на одной и той же работе. |
| 410 | Срок хранения JSON истек после часов 24. Используйте сохраненную копию; доставленный носитель имеет собственное хранилище. |

#### CLI

##### Проверить сохраненную работу · Bash / jq

```bash
# Bash + jq. CLI receipts use remoteId; HTTP receipts use id.
(
set -e
JOB_ID=$(jq -er '.remoteId // .id' submission.json)
flashdata jobs get "$JOB_ID" --json
)
```

##### По-прежнему работает · используйте возвращенный JOB_ID

```bash
flashdata jobs wait JOB_ID
```

##### Завершено · используйте новое имя файла вывода

```bash
flashdata jobs result JOB_ID --output recovered-result.json
```


#### HTTP / cURL

##### Проверить сохраненную работу

```bash
# Bash + cURL + jq. Read the saved async submission receipt.
(
set -e
test -n "$FLASHDATA_API_KEY" || { printf 'Set FLASHDATA_API_KEY first\n' >&2; exit 1; }
STATUS_URL=$(jq -er '(.submission // .).links[]
  | select(.rel == "self") | .href' submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Accept: application/json' \
  "$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)
```


- [Опрос HTTP и поиск результатов](https://flashdata.dev/ru/docs/guides/async-batch/reference.md)
- [Вместимость в ожидании работы](https://flashdata.dev/ru/docs/guides/usage-and-limits/reference.md)

<a id="uncertain"></a>

### Тайм-аут / 5xx: была ли принята задача?

Проверьте исходный запуск и History перед повторным использованием POST. Восстановление подтвержденной принятой работы. Если приемка неизвестна, продолжайте работать с ID и контактной поддержкой; изменение IDs и повторное представление могут дублировать заряды.

#### Проверить сначала · заменить RUN_ID

```bash
flashdata runs show RUN_ID
```

#### Восстановление подтвержденной принятой работы

```bash
flashdata runs recover RUN_ID
```

- [Запросить историю](https://flashdata.dev/app/jobs)
- [Решения о восстановлении](https://flashdata.dev/ru/docs/guides/agent-recovery/reference.md)

<a id="output"></a>

### CLI output_exists: файл результата уже существует

CLI не перезаписывает файлы --output. Прочитайте существующий файл или выберите новое имя файла вывода, сохраняя при этом исходный --run-id и запрос. Не изобретайте новый запуск ID, чтобы обойти эту ошибку.

#### Проверить оригинальную версию

```bash
flashdata runs show RUN_ID
```

- [Вывод файлов и запуск восстановления](https://flashdata.dev/ru/docs/guides/cli-automation/reference.md)

<a id="results"></a>

### Пустой поиск, недостающие подписи или нечитаемые загрузки

Эти команды читают только локальные файлы результатов, а не только CLI? stdout конверт.

#### Google Search

Если статус завершен и органический пуст, ослабьте фильтры запросов. Держите пустой результат в записи задачи.

##### Проверка сохраненных результатов · Bash/jq

```bash
jq '{status, usage, resultCount: (.results | length)}' result.json
jq '(.results[0].organic // []) | length' result.json
```

- [Поисковые фильтры и пагинация](https://flashdata.dev/ru/docs/guides/google-search-guide/reference.md)

#### YouTube подписи

Метаданные перечисляют языковые коды, независимо от того, является ли трек ручным или автоматическим. Выберите перечисленный язык и установите авто explicitly: true для автоматического, false для ручного. Никакая соответствующая дорожка не означает никаких подписей для этого выбора; FlashData не генерирует замены.

##### Проверка доступных языков · Bash / jq

```bash
jq '.results[0].transcriptLanguages' metadata.json
```

- [Выберите трек подписи](https://flashdata.dev/ru/docs/guides/youtube-data-guide/reference.md#captions)

#### YouTube Download

Прочитайте заполненную квитанцию delivery.json. Загрузите объект с помощью учетных данных о местонахождении, а затем сравните его размер и MD5 с квитанцией. Частный file_url не становится общедоступным после доставки.

##### Проверка доставки · Bash / jq

```bash
jq '.results[0] | {file_url, file_size, md5}' delivery.json
```

- [Проверьте размер и контрольную сумму](https://flashdata.dev/ru/docs/guides/youtube-download-guide/reference.md#delivery)


<a id="mcp"></a>

### Инструменты MCP отсутствуют или срок аутентификации истек

Проверьте хост, выполняющий задание. Перечисленный сервер подтверждает конфигурацию, а не рабочее соединение. Если настроенное хостируемое соединение OAuth требует входа в систему, запуска команды входа в систему и полного одобрения браузера, то обновите список инструментов.

#### Codex

Откройте /mcp в Codex CLI для проверки состояния соединения и инструментов. В приложении проверьте настроенный сервер и начните новый сеанс после изменения настройки.

##### Проверьте конфигурацию

```bash
codex mcp list
```

##### Только когда требуется вход OAuth

```bash
codex mcp login flashdata --scopes mcp:research
```

- [Настройка сервера Codex](https://flashdata.dev/ru/docs/integrations/codex/reference.md)

#### OpenClaw

##### Проверить сконфигурированный сервер

```bash
openclaw mcp doctor flashdata --probe
```

##### Только когда требуется вход OAuth

```bash
openclaw mcp login flashdata
openclaw mcp doctor flashdata --probe
```

- [Настройка сервера OpenClaw](https://flashdata.dev/ru/docs/integrations/openclaw/reference.md)

#### Ключ API / локальный сервер

Логин OAuth не восстанавливает соединение API-ключ. Проверьте ключ в среде хоста и его исходные разрешения. Для локального стио проверьте требование Node.js пакета MCP и перезапустите хост после обновления его среды.

##### Для местного стука

```bash
node --version
```

- [Хостинг API-ключа и локальной настройки MCP](https://flashdata.dev/ru/docs/integrations/mcp-clients/reference.md)


<a id="skills"></a>

### Навык установлен, но агент не может найти или использовать его.

Проверьте тот же проект, профиль хоста и место установки, а затем начните новую сессию агента. Навыки выполнения задач CLI нужны CLI; Flashdata-mcp нужен подключенный сервер MCP. Установка навыка не подключает сервер или не предоставляет разрешения на учетную запись.

#### Codex · CLI навыки

##### Проверьте набор навыков CLI по умолчанию

```bash
flashdata skills verify --agent codex
```


#### Codex · MCP навыки

##### Проверьте только необязательный навык MCP

```bash
flashdata skills verify --agent codex --skill flashdata-mcp
```


#### OpenClaw

##### Проверьте наличие навыков

```bash
openclaw skills list --eligible
openclaw skills check
```


- [Установка или обновление навыков](https://flashdata.dev/ru/docs/guides/agent-skill/reference.md)
- [Подключение MCP](https://flashdata.dev/ru/docs/integrations/mcp-clients/reference.md)

<a id="faq"></a>

## Часто задаваемые вопросы


<a id="faq-access"></a>

### Подключение

| Вопрос | Ответить |
| --- | --- |
| Нужен ли мне ИИ-агент? | Нет. Используйте HTTP API, Go/Python/TypeScript SDK, CLI или консоль напрямую. MCP и навыки являются дополнительными опциями для агентов. |
| Какой интерфейс выбрать? | Используйте SDK или HTTP API внутри приложения, CLI для терминальных задач и MCP для хоста с поддержкой MCP. Навыки предоставляют инструкции для задач CLI или подключенных инструментов MCP; они не заменяют аутентификацию. |
| Могу ли я повторно использовать учетные данные для повторяющихся задач? | Да. Используйте доступ владельца и сохраните тот же защищенный профиль CLI, секрет времени выполнения или соединение MCP. Для доступа к ключу API проверьте recurringAllowed: true. Ваш хозяин или планировщик запускает расписание. |
| Удаление локальных настроек отменяет доступ? | Нет. Отмените ключ API или соединение в консоли. Удаление локальных настроек удаляет только эту локальную копию. |

- [Выберите интерфейс](https://flashdata.dev/ru/docs/reference.md)
- [Повторяющаяся настройка задачи](https://flashdata.dev/ru/docs/guides/recurring-tasks/reference.md)
- [Связанные агенты](https://flashdata.dev/app/settings/connections)

<a id="faq-billing"></a>

### Испытания и кредиты

| Вопрос | Ответить |
| --- | --- |
| Может ли агент попробовать FlashData до регистрации? | Да, с правом временного доступа через CLI или на борту API. Повторное использование одного и того же профиля и регистрационных доказательств. Потребность в постоянном использовании или существующий ключ API. |
| Даёт ли привязка дополнительный пробный баланс? | Сама по себе претензия не дает никаких дополнительных пробных кредитов. Будущие запросы используют баланс счета владельца; неиспользованные временные кредиты не передаются. Недавно созданная учетная запись следует обычной политике регистрационных кредитов. |
| Сколько запросов могут покрыть мои кредиты? | Проверьте баланс счета и цены источника. Количество запросов зависит от источника, а задачи со смешанным исходным кодом имеют один баланс. YouTube Download оценивается по загруженным байтам, а не по фиксированному количеству запросов. |

- [Пробный доступ и привязка к аккаунту](https://flashdata.dev/ru/docs/guides/agent-onboarding/reference.md)
- [Вычислить количество запросов](https://flashdata.dev/ru/docs/guides/credits-and-billing/reference.md)
- [Ограничения на регистрацию и запрос](https://flashdata.dev/ru/docs/guides/usage-and-limits/reference.md)

<a id="faq-results"></a>

### Источники и результаты

| Вопрос | Ответить |
| --- | --- |
| Почему мой агент может искать, но не скачивать? | Для загрузки необходим доступ владельца, разрешение youtube_download и хранилище назначения. Временные испытания и mcp:research OAuth не включают загрузку. Авторизованный владелец ключа API может использовать его через CLI, HTTP или MCP. |
| Google Search возвращает полные веб-страницы? | Он возвращает результаты поиска и выдержки. Ваше приложение или агент читает выбранный URLs. |
| FlashData генерирует видео резюме или подписи? | Он извлекает метаданные и существующие подписи. Он не генерирует недостающие подписи; ваша модель пишет резюме из доступных результатов. |

- [Google Search](https://flashdata.dev/ru/docs/guides/google-search-guide/reference.md)
- [YouTube Data](https://flashdata.dev/ru/docs/guides/youtube-data-guide/reference.md)
- [YouTube Download](https://flashdata.dev/ru/docs/guides/youtube-download-guide/reference.md)

<a id="support"></a>

## Все еще застрял? Отправить минимальный отчет

Сохраните ошибку HTTP или CLI JSON от stderr как diagnostic.json. Извлекать идентификаторы можно только после неисправной команды. Храните ключи, текст частного запроса и подписанный URLs из отчета. Для ответов, не относящихся к JSON, сообщите о статусе HTTP от diagnostic-status.txt.

### Захват бесплатной проверки доступа CLI · Bash

```bash
flashdata auth status --json 2> diagnostic.json
```

### Идентификаторы ошибок извлечения · Bash / jq

```bash
# A saved HTTP error or CLI --json error; local files only.
date -u '+%Y-%m-%dT%H:%M:%SZ'
jq '(.error // .) as $e | {
  status: ($e.httpStatus // $e.status),
  code: $e.code,
  requestId: $e.requestId,
  runId: (.runId // $e.runId),
  jobId: $e.remoteId,
  retryAfter: $e.retryAfter
} | with_entries(select(.value != null))' diagnostic.json
```

### Доклад о поддержке

```text
Время UTC:
Клиент + версия:
Источник + этап (auth / submit / poll / fetch):
HTTP статус + код ошибки:
Запросить ID / задание ID / запустить ID:
Результаты представления: принято/отклонено/неизвестно
Ожидаемый результат против фактического:
```

- [Ссылка на код ошибки](https://flashdata.dev/ru/docs/errors/reference.md)
- [Связаться с поддержкой](https://flashdata.dev/ru/contact)
