Browse documentation
API reference
Find the cause of a failed request and decide whether to fix it, wait or retry.
On this page
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. |
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 errors commonly include error and message; code is optional. Authentication errors may use success: false instead of error: true.
{
"error": true,
"code": "unsupported_representation",
"message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}V2 problem responses use application/problem+json. Keep requestId for support. Validation errors can also include fieldErrors with field, code and message.
{
"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."
}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.
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'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. |
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. |
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'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. |
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.