# Erros e códigos de status

Ache a causa de um pedido fracassado e decida se consertará, esperará ou tentará novamente.

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

<a id="status-codes"></a>

## Códigos de status HTTP

Comece com o status HTTP, então leia o código de erro e a mensagem para a causa específica.

| Status | O que quer dizer? | O que fazer |
| --- | --- | --- |
| 400 | Pedido inválido | Conserte a fonte, campos obrigatórios, tipos de parâmetros ou cabeçalhos de resposta antes de tentar novamente. |
| 401 | A autenticação falhou | Verifique X-API-Key. Substituir uma chave expirada ou revogada, tentar a mesma chave não vai ajudar. |
| 402 | Créditos insuficientes | Verifique o saldo da conta. Adicione créditos ou deixe o dono da conta resolver o acesso antes de enviar novamente. |
| 403 | Acesso negado | Verifique as permissões da chave e o status da conta ou assinatura. |
| 404 | Não encontrado | Verifique o URL, o trabalho ID e a conta. trabalhos fora de sua conta ou fontes permitidas também podem devolver 404. |
| 406 | Tipo de resposta não aceitável | Use Accept: application/json ou text/plain. Select Markdown com X-Respond-With: markdown. |
| 409 | Resultado não pronto / conflito | Em um resultado lido, pesquise o trabalho existente até que ele termine. Para outros objetivos, resolva o conflito descrito no corpo. |
| 410 | Resultado expirado | Use uma cópia salva. Tentando novamente o resultado URL não pode restaurar um resultado expirado. |
| 422 | Entrada inválida / tarefa falhada | Conserte os campos relatados. Em uma leitura de resultado, inspecione job.error: um trabalho fracassado não tem nenhum resultado bem sucedido para buscar. |
| 429 | Limite atingido | Espere por Retry-After ou retry_after. Reduza a taxa de solicitação; para uma fila pendente, aguarde os trabalhos existentes para finish. |
| 500 / 502 / 503 / 504 | Serviço ou falha de montante | Tente ler novamente com o limite. Para um intervalo POST ou submissão, verifique se o trabalho foi aceito antes de enviá-lo novamente. |

- [Verifique as chaves API](https://flashdata.dev/app/api-keys)
- [Créditos e preços](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md)
- [Limites de taxa](https://flashdata.dev/pt/docs/guides/usage-and-limits/reference.md)

<a id="response"></a>

## Leia uma resposta de erro

Erros API usam JSON, inclusive quando você pede texto simples. O corpo difere pelo ponto final. Ramo no status e código HTTP quando presente, use mensagem ou detalhes para explicar o problema.

### Consulta API

Erros de consulta geralmente incluem erro e mensagem; código é opcional. Erros de autenticação podem usar success: false em vez de error: true.

#### 400 · application/json

```json
{
  "error": true,
  "code": "unsupported_representation",
  "message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}
```


### API de gerenciamento

Respostas de problemas V2 usam application/problem+json. Mantenha requestId para apoio. Erros de validação também podem incluir fieldErrors com campo, código e mensagem.

#### 401 · application/problem+json

```json
{
  "type": "https://api.flashdata.dev/problems/invalid_api_key",
  "title": "Invalid API Key",
  "status": 401,
  "code": "invalid_api_key",
  "requestId": "example-request-id",
  "detail": "The API Key is invalid or unavailable."
}
```



<a id="diagnostics"></a>

## Inspecione status, cabeçalhos e corpo

Use curl --include para ver todos os três. Este exemplo verifica sua chave com uma conta livre lida; ela não envia uma consulta. Coloque FLASHDATA_API_KEY em seu ambiente primeiro.

### Inspecione uma resposta. cURL / Bash

```bash
curl --include --silent --show-error --max-time 20 \
  'https://api.flashdata.dev/v2/api-access/identity' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [Configuração de autenticação](https://flashdata.dev/pt/docs/guides/headers-and-authentication/reference.md)
- [Solução de problemas por sintoma](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md)

<a id="retries"></a>

## Quando tentar novamente

Uma repetição do POST pode criar outra consulta. Um tempo limite não prova que o primeiro pedido foi rejeitado. Salve o trabalho ID assim que receber.

| Situação | Próxima ação |
| --- | --- |
| Entrada, chave, permissão ou equilíbrio inválidos | Pare. Conserte o pedido ou o estado da conta antes de tentar de novo, não perca tempo com esses erros. |
| 429 com uma dica de espera | Honor Retry-After (segunda data ou data HTTP), ou o valor JSON retry_after em segundos. Se ambos estiverem presentes, use o atraso mais longo. |
| Pedido de leitura: 429 / erro temporário de rede 5xx | Tente novamente o mesmo GET. Sem uma dica de espera, use atrasos crescentes com nervosismo, uma contagem máxima de tentativas e um limite de tempo. |
| POST tempo limite ou 5xxx ambíguo | Mantenha o trabalho existente ID e verifique seu status. Se nenhum ID foi recebido, inspecione o histórico de trabalho antes de decidir se submeter novamente. |

- [História do trabalho](https://flashdata.dev/app/jobs)
- [Recupere uma tarefa de agente](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)

<a id="job-status"></a>

## verificação um trabalho de fundo

HTTP 200 do ponto final do estado significa que a leitura foi bem sucedida. Verifique job.status para saber se a tarefa foi bem sucedida. Defina JOB_ID para o seu trabalho existente; este comando não envia uma substituição.

| job.status | O que fazer |
| --- | --- |
| pending / processing | Espere, então pesquise o mesmo trabalho. Um resultado lido retorna 409 até a conclusão. |
| completed | Recupere e salve o resultado. Os resultados originais do JSON retornam um redirecionamento de armazenamento 302; os resultados formatados retornam um corpo diretamente. |
| failed | Pare de fazer pesquisas e inspecione job.error. O resultado final devolve 422 com código result_not_ready para um trabalho fracassado. |

### Leia status do trabalho · cURL / Bash

```bash
curl --fail-with-body --silent --show-error --max-time 30 \
  "https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [Verifique o status de Python e cURL](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#status)
- [Recupere resultados completados](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#results)
- [Bulk progresso no trabalho](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md#getBulkJob)

<a id="response-formats"></a>

## Erros de formatação de resposta

| Status / código | Consertar |
| --- | --- |
| 400 · unsupported_representation | Coloque X-Respond-With para marcar, ou remova o cabeçalho. |
| 406 · not_acceptable | Defina Accept para application/json ou text/plain; use UTF-8 se especificar uma codificação. |

- [Requisito e formatação de resposta exemplos](https://flashdata.dev/pt/docs/guides/response-formats/reference.md)

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

## Consiga ajuda com um pedido

Envie o endpoint, horário de UTC, status HTTP, código de erro e solicitação ou trabalho ID. Remova as chaves API, fichas e assinou URLs do relatório.

- [Falar com o suporte](https://flashdata.dev/pt/contact)
