# Perguntas frequentes e solução de problemas

Verifique seu acesso, conserte um pedido fracassado ou encontre uma resposta sobre usar FlashData.

Referência canônica: https://flashdata.dev/pt/docs/guides/troubleshooting
2026-11-04 por FlashData

- [Conserte um erro](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#fix) — Comandos e correções por sintoma
- [Perguntas comuns](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#faq) — Acesso, créditos e dados

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

## Comece com um verificação de acesso gratuito

Verifique onde a tarefa falhou. Use suas credenciais existentes, esses comandos não enviam uma consulta.

### CLI

Use seu acesso CLI salvo. Para um perfil nomeado, adicione o nome --profile a cada comando. Essas leituras não gastam créditos de consulta.

#### Conta livre lê

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

- [Prepare uma chave](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md#store)

### Bash / cURL

Use o FLASHDATA_API_KEY existente no mesmo terminal, container ou trabalho agendado. Requer cURL 7.76+.

#### Leia a conta 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

Use o FLASHDATA_API_KEY existente no mesmo terminal, container ou trabalho agendado.

#### Leia a conta 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: credenciais](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#credentials)
- [402: créditos](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#credits)
- [429: limite de taxa](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#rate-limit)
- [400 / 422: pedido](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#request)
- [Pendente ou fracassou no trabalho](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#jobs)
- [Tempo limite, 5xx](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#uncertain)
- [Ligação MCP](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#mcp)

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

### O que verificar?

A identidade deve ter access: ready e incluir sua fonte em escopos. Em CLI JSON, a identidade está em data.identity.identity; também requer data.accessVerified: true. Um comando bem sucedido com accessVerified: false não verificou o acesso.

Para um perfil chamado CLI, adicione --profile Nome a cada comando abaixo. Mantenha o --state-dir original e o OS usuário. FLASHDATA_API_KEY substitui uma chave salva CLI; SDKs e anfitriões MCP usam sua própria configuração credencial.


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

## Encontre e conserte o problema

Abra o sintoma que bate com o seu erro. Use IDs e recibos da tarefa original.


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

### Comando não encontrado ou perfil faltando

Sem executável: instale o lançamento do seu OS/CPU e adicione seu diretório ao PATH. Perfil em falta: use o usuário OS original e diretório de estado. Verifique dentro do agendador ou recipiente, também.

#### Bash

##### Localize o executável

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


#### PowerShell

##### Localize o executável

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


- [Instalação CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#install)
- [Perfil e diretórios estaduais](https://flashdata.dev/pt/docs/guides/cli-automation/reference.md#profiles)

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

### 401 / 403: chave, escopo ou validade

Para substituir uma chave de dono salva, cole a chave aprovada no prompt escondido. Se o FLASHDATA_API_KEY estiver definido, atualize esse segredo no tempo de execução; salvar outra chave CLI não irá sobrepor.

1. 401 Verifique se a chave está vencida, revogada ou incorretamente configurada. 403Compare a fonte solicitada com o escopo da identidade.
2. REST e SDKs usam X-API-Key. Um símbolo MCP OAuth não pode substituir uma chave API. Para acesso temporário, use a cobrança abaixo.

#### Substitua e verifique uma chave de dono salva

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

- [Permissões chave e rotação](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md#rotate)
- [vinculação de recuperação](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#claim)
- [MCP reconectar](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#mcp)

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

### vinculação aprovada, mas o agente ainda tem acesso a teste.

Termine a entrega no mesmo perfil CLI que criou a vinculação. O proprietário completa a inscrição, verificação por e-mail e consentimento no navegador, o CLI recebe a credencial.

#### Já aprovado

##### Termine e verifique

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


#### Link expirado

Peça um novo link para o teste existente, deixe o proprietário aprovar, e então execute auth finish. Não execute init novamente.

##### Renove a ligação de vinculação

```bash
flashdata auth claim
```


- [Reclamando e entregando](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md#help)
- [Verifique o acesso do proprietário para tarefas recorrentes](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)

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

### 402- Créditos insuficientes

Compare availableCredits com o preço atual para sua fonte. Reivindicar um teste esgotado para usar o equilíbrio do proprietário, ou deixar o proprietário rever Billing antes de tentar novamente.

#### CLI

Use seu acesso CLI salvo. Para um perfil nomeado, adicione o nome --profile a cada comando. Essas leituras não gastam créditos de consulta.

##### Conta livre lê

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

- [Prepare uma chave](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md#store)

#### Bash / cURL

Use o FLASHDATA_API_KEY existente no mesmo terminal, container ou trabalho agendado. Requer cURL 7.76+.

##### Leia a conta 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

Use o FLASHDATA_API_KEY existente no mesmo terminal, container ou trabalho agendado.

##### Leia a conta 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)
- [Teste e vinculação à conta](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md)
- [Preços para outras fontes](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md)

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

### 429 Espere antes de tentar novamente

Leia Retry-After na resposta falhada: segundos ou uma data HTTP. Espere até lá e reduza a concorrência. O registro de teste permite três registros por IP por janela 24-hora, reutilizar o perfil original e a prova de registro.

Esta leitura gratuita demonstra salvar cabeçalhos, status e corpo. Use o Retry-After da operação que falhou; consulta, registro e limites de leitura de conta podem ser diferentes.

#### Capture a resposta! 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
)
```

#### Inspecione a capacidade da conta

```bash
flashdata account limits
```

- [Limites de taxa e recuo](https://flashdata.dev/pt/docs/guides/usage-and-limits/reference.md)

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

### 400 / 422: entrada ou falha de processamento rejeitada

Código de leitura, detalhes e fieldErrors do erro HTTP. Corrija o corpo do pedido, guarde-o como request.json, então valide-o. Mantenha as credenciais de armazenamento em um arquivo privado. Se 422 vem de um trabalho existente, inspecione job.error primeiro.

#### Validar sem uma submissão paga

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

- [Referências do pedido de fonte](https://flashdata.dev/pt/docs/reference/reference.md)
- [Entrada de download privada](https://flashdata.dev/pt/docs/guides/cli-automation/reference.md#storage)
- [Inspecione um trabalho existente](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#jobs)

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

### Trabalho pendente, ou HTTP 200 com um trabalho fracassado

Leia o trabalho do submission.json, seu recibo salvo. HTTP 200 significa que o status lido foi bem sucedido; job.status é o resultado da tarefa (data.status em CLI JSON). Para Batch, salve a entrada relevante de consultas como submission.json.

| Estado ou erro | Próxima ação |
| --- | --- |
| pending / processing | Espere no mesmo trabalho, não o submeta novamente. |
| completed | Busque e salve o resultado existente. |
| failed | Inspecione job.error antes de enviar o trabalho corrigido. |
| 404 | Verifique o trabalho ID e a conta de submissão. |
| 409 | Os resultados não estão prontos. Continue pesquisando o mesmo trabalho. |
| 410 | JSON expirado após as horas de 24. Use sua cópia salva, a mídia entregue tem sua própria retenção de armazenamento. |

#### CLI

##### Inspecione o trabalho salvo. 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
)
```

##### Ainda correndo, use o JOB_ID de volta

```bash
flashdata jobs wait JOB_ID
```

##### Concluído · use um novo nome de arquivo de saída

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


#### HTTP / cURL

##### Inspecione o trabalho salvo

```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 pesquisa e recuperação de resultados](https://flashdata.dev/pt/docs/guides/async-batch/reference.md)
- [Capacidade de trabalho pendente](https://flashdata.dev/pt/docs/guides/usage-and-limits/reference.md)

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

### Tempo limite / 5xx: a tarefa foi aceita?

Inspecione a corrida original e History antes de tentar novamente um POST. Recupere um trabalho aceito. Se a aceitação for desconhecida, mantenha o controle ID e o suporte de contato, mudar IDs e reenviar pode duplicar as cargas.

#### Inspecione primeiro · substituir RUN_ID

```bash
flashdata runs show RUN_ID
```

#### Recupere o trabalho confirmado e aceite

```bash
flashdata runs recover RUN_ID
```

- [Requisito histórico](https://flashdata.dev/app/jobs)
- [Decisões de recuperação](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)

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

### CLI output_exists: arquivo de resultados já existe

O CLI não substitui arquivos --output. Leia o arquivo existente, ou escolha um novo nome de saída enquanto mantém o --run-id original e solicita. Não invente uma nova corrida ID para contornar esse erro.

#### Inspecione a corrida original

```bash
flashdata runs show RUN_ID
```

- [Arquivos de saída e recuperação de execução](https://flashdata.dev/pt/docs/guides/cli-automation/reference.md)

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

### Busca vazia, legendas perdidas ou download ilegível

Esses comandos só lêem arquivos de resultados locais, não o envelope do CLI.

#### Google Search

Se o status for feito e o orgânico estiver vazio, solte os filtros de consulta. Mantenha o resultado vazio em seu registro de tarefas.

##### Inspecione resultados salvos. Bash / jq

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

- [Filtros de busca e paginação](https://flashdata.dev/pt/docs/guides/google-search-guide/reference.md)

#### YouTube legendas

Metadados listam códigos de linguagem, não se uma faixa é manual ou automática. Escolha um idioma listado e ajuste o explicitly: true automático, false manual. Nenhuma pista correspondente significa nenhuma legenda para essa seleção; FlashData não gera uma substituição.

##### Inspecione as línguas disponíveis. Bash / jq

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

- [Selecione uma faixa de legendas](https://flashdata.dev/pt/docs/guides/youtube-data-guide/reference.md#captions)

#### YouTube Download

Leia o recibo delivery.json completo. Baixe o objeto com suas credenciais de armazenamento de destino, e compare seu tamanho e MD5 com o recibo. Um file_url privado não se torna público após a entrega.

##### Inspecione a entrega. Bash / jq

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

- [Verifique o tamanho e o checksum](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md#delivery)


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

### MCP ferramentas faltando ou autenticação expirada

Verifique o anfitrião executando a tarefa. Um servidor listado confirma a configuração, não uma conexão funcional. Se a conexão OAuth configurada requer login, execute seu comando de login e complete a aprovação do navegador, então atualize a lista de ferramentas.

#### Codex

Abra /mcp no Codex CLI para verificar o status da conexão e ferramentas. No aplicativo, verifique o servidor configurado e comece uma nova sessão após as mudanças de configuração.

##### Verifique a configuração

```bash
codex mcp list
```

##### Só quando o login do OAuth é necessário

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

- [Configuração do servidor Codex](https://flashdata.dev/pt/docs/integrations/codex/reference.md)

#### OpenClaw

##### Sonda o servidor configurado

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

##### Só quando o login do OAuth é necessário

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

- [Configuração do servidor OpenClaw](https://flashdata.dev/pt/docs/integrations/openclaw/reference.md)

#### API chave / servidor local

O login do OAuth não repara uma conexão API-key. Verifique a chave no ambiente do hospedeiro e suas permissões de origem. Para a Stdio local, verifique o requisito MCP do pacote Node.js e reinicie o host após atualizar seu ambiente.

##### Para o stdio local

```bash
node --version
```

- [Sediado com chave API e configuração local MCP](https://flashdata.dev/pt/docs/integrations/mcp-clients/reference.md)


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

### Habilidade instalada, mas o agente não pode encontrá-la ou usá-la.

Verifique o mesmo projeto, perfil do host e instale o local, e comece uma nova sessão de agentes. As habilidades de tarefa CLI precisam do CLI; flashdata-mcp precisa de um servidor MCP conectado. Instalar uma habilidade não conecta um servidor ou concede permissões de conta.

#### Codex · CLI habilidades

##### Verifique o pacote de habilidades padrão CLI

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


#### Codex · MCP habilidade

##### Verifique apenas a habilidade opcional MCP

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


#### OpenClaw

##### Verifique a disponibilidade de habilidades

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


- [Instale ou atualize habilidades](https://flashdata.dev/pt/docs/guides/agent-skill/reference.md)
- [Conectar MCP](https://flashdata.dev/pt/docs/integrations/mcp-clients/reference.md)

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

## Perguntas frequentes


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

### Se conectando

| Pergunta | Responda |
| --- | --- |
| Preciso de um agente de IA? | Não. Use HTTP API, Go/Python/TypeScript SDK, CLI ou console diretamente. MCP e habilidades são opções adicionais para agentes. |
| Qual interface devo escolher? | Use um SDK ou HTTP API dentro de um aplicativo, o CLI para tarefas terminais, e MCP para um hospedeiro com capacidade para MCP. Habilidades fornecem instruções para tarefas CLI ou ferramentas MCP conectadas; elas não substituem a autenticação. |
| Posso reutilizar credenciais para tarefas recorrentes? | Sim. Use o acesso do proprietário e mantenha o mesmo perfil protegido CLI, segredo de execução ou conexão MCP. Para acesso chave API, verifique recurringAllowed: true. Seu anfitrião ou agendador executa a programação. |
| Apagar as configurações locais revoga o acesso? | Não. Revogue a chave API ou conexão no console. Excluir as configurações locais só remove essa cópia local. |

- [Escolha uma interface](https://flashdata.dev/pt/docs/reference.md)
- [Configuração da tarefa recorrente](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)
- [Agentes conectados](https://flashdata.dev/app/settings/connections)

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

### testes e créditos

| Pergunta | Responda |
| --- | --- |
| Um agente pode tentar FlashData antes de se inscrever? | Sim, com acesso temporário elegível através do CLI ou a bordo do API. Reutilize o mesmo perfil e a mesma prova de registro. Necessidades de uso contínuo ou uma chave API existente. |
| Alegando adicionar outra bolsa para teste? | Se reivindicar não dá créditos extras. Pedidos futuros usam o saldo da conta do proprietário, créditos temporários não usados não são transferidos. Uma conta recém-criada segue a política normal de inscrição-crédito. |
| Quantos pedidos meus créditos podem cobrir? | Verifique o saldo da conta e o preço da fonte. A contagem de pedidos depende da fonte, e tarefas mistas compartilham um equilíbrio. YouTube Download é pago por bytes baixados, não uma contagem fixa de pedidos. |

- [Teste e vinculação à conta](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md)
- [Calcule a contagem de pedidos](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md)
- [Limites de registro e solicitação](https://flashdata.dev/pt/docs/guides/usage-and-limits/reference.md)

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

### Fontes e resultados

| Pergunta | Responda |
| --- | --- |
| Por que meu agente pode procurar, mas não baixar? | O download precisa de acesso ao proprietário, permissão youtube_download e armazenamento de destino. Testes temporários e mcp:research OAuth não incluem download. Uma chave API autorizada pode usá-la através de CLI, HTTP ou MCP. |
| Google Search retorna todas as páginas da web? | Ele retorna resultados de busca e trechos. Seu aplicativo ou agente lê o URLs selecionado. |
| FlashData gera resumos de vídeo ou legendas? | Recupera metadados e legendas existentes. Não gera legendas faltando, seu modelo escreve um resumo dos resultados disponíveis. |

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

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

## Ainda preso? Envie um relatório mínimo

Salve o corpo de erro HTTP ou o erro CLI JSON de stderr como diagnostic.json. Extrair identificadores apenas após um comando falhado. Mantenha as chaves, texto de consulta privada e assinou URLs fora do relatório. Para respostas não JSON, reporte o status HTTP de diagnostic-status.txt.

### Capturar um livre CLI  Checagem de acesso. Bash

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

### Extrair identificadores de erro · 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
```

### Relatório de apoio

```text
Hora da UTC:
 Cliente + versão:
 Fonte + fase (auth / enviar / votação / buscar):
HTTP status + código de erro:
 Solicitar ID / trabalho ID / execução ID:
 Resultado da submissão: aceito/rejeitado/desconhecido
 Espera-se contra o resultado real:
```

- [Referência do código de erro](https://flashdata.dev/pt/docs/errors/reference.md)
- [Falar com o suporte](https://flashdata.dev/pt/contact)
