# Errors and status codes

Find the cause of a failed request and decide whether to fix it, wait or retry.

Canonical reference: https://flashdata.dev/docs/errors
Reviewed: 2026-11-04 by FlashData

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

## HTTP status codes

Start with the HTTP status, then read the error code and message for the specific cause.

| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | Invalid request | Fix the source, required fields, parameter types or response headers before retrying. |
| 401 | Authentication failed | Check X-API-Key. Replace an expired or revoked key; retrying the same key will not help. |
| 402 | Insufficient credits | Check the account balance. Add credits or let the account owner resolve access before submitting again. |
| 403 | Access denied | Check the key's source permissions and account or subscription status. |
| 404 | Not found | Check the URL, job ID and account. Jobs outside your permitted account or sources can also return 404. |
| 406 | Response type not acceptable | Use Accept: application/json or text/plain. Select Markdown with X-Respond-With: markdown. |
| 409 | Result not ready / conflict | On a result read, poll the existing job until it completes. For other endpoints, resolve the conflict described in the body. |
| 410 | Result expired | Use a saved copy. Retrying the result URL cannot restore an expired result. |
| 422 | Invalid input / failed job | Fix the reported fields. On a result read, inspect job.error: a failed job has no successful result to fetch. |
| 429 | Limit reached | Wait for Retry-After or retry_after. Reduce request rate; for a full pending queue, wait for existing jobs to finish. |
| 500 / 502 / 503 / 504 | Service or upstream failure | Retry reads with bounded backoff. For a POST or submission timeout, check whether work was accepted before sending it again. |

- [Check API keys](https://flashdata.dev/app/api-keys)
- [Credits and pricing](https://flashdata.dev/docs/guides/credits-and-billing/reference.md)
- [Rate limits](https://flashdata.dev/docs/guides/usage-and-limits/reference.md)

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

## Read an error response

API errors use JSON, including when you request plain text. The body differs by endpoint. Branch on the HTTP status and code when present; use message or detail to explain the problem.

### Query API

Query errors commonly include error and message; code is optional. Authentication errors may use success: false instead of 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."
}
```


### Management API

V2 problem responses use application/problem+json. Keep requestId for support. Validation errors can also include fieldErrors with field, code and message.

#### 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>

## Inspect status, headers and body

Use curl --include to see all three. This example checks your key with a free account read; it does not submit a query. Set FLASHDATA_API_KEY in your environment first.

### Inspect a response · 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'
```

- [Authentication setup](https://flashdata.dev/docs/guides/headers-and-authentication/reference.md)
- [Troubleshoot by symptom](https://flashdata.dev/docs/guides/troubleshooting/reference.md)

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

## When to retry

A repeated POST can create another billable query. A network timeout does not prove that the first request was rejected. Save the job ID as soon as you receive it.

| Situation | Next action |
| --- | --- |
| Invalid input, key, permission or balance | Stop. Fix the request or account state before retrying; do not loop on these errors. |
| 429 with a wait hint | Honor Retry-After (seconds or HTTP date), or the JSON retry_after value in seconds. If both are present, use the longer delay. |
| Read request: 429 / temporary 5xx / network error | Retry the same GET. Without a wait hint, use increasing delays with jitter, a maximum attempt count and a time limit. |
| POST timeout or ambiguous 5xx | Keep the existing job ID and check its status. If no ID was received, inspect job history before deciding to submit again. |

- [Job history](https://flashdata.dev/app/jobs)
- [Recover an agent task](https://flashdata.dev/docs/guides/agent-recovery/reference.md)

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

## Check a background job

HTTP 200 from the status endpoint means the read succeeded. Check job.status to know whether the task succeeded. Set JOB_ID to your existing job; this command does not submit a replacement.

| job.status | What to do |
| --- | --- |
| pending / processing | Wait, then poll the same job. A result read returns 409 until completion. |
| completed | Retrieve and save the result. Original JSON results return a 302 storage redirect; formatted results return a body directly. |
| failed | Stop polling and inspect job.error. The result endpoint returns 422 with code result_not_ready for a failed job. |

### Read job status · 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'
```

- [Check status · Python and cURL](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#status)
- [Retrieve completed results](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#results)
- [Bulk job progress](https://flashdata.dev/docs/reference/bulk-processing/reference.md#getBulkJob)

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

## Response-format errors

| Status / code | Fix |
| --- | --- |
| 400 · unsupported_representation | Set X-Respond-With to markdown, or remove the header. |
| 406 · not_acceptable | Set Accept to application/json or text/plain; use UTF-8 if specifying a charset. |

- [Request and response format examples](https://flashdata.dev/docs/guides/response-formats/reference.md)

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

## Get help with a request

Send the endpoint, UTC timestamp, HTTP status, error code and request or job ID. Remove API keys, tokens and signed URLs from the report.

- [Contact support](https://flashdata.dev/contact)
