Skip to content
EN
Get API key
Browse documentation

API reference

Errors and status codes

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.

StatusMeaningWhat to do
400Invalid requestFix the source, required fields, parameter types or response headers before retrying.
401Authentication failedCheck X-API-Key. Replace an expired or revoked key; retrying the same key will not help.
402Insufficient creditsCheck the account balance. Add credits or let the account owner resolve access before submitting again.
403Access deniedCheck the key's source permissions and account or subscription status.
404Not foundCheck the URL, job ID and account. Jobs outside your permitted account or sources can also return 404.
406Response type not acceptableUse Accept: application/json or text/plain. Select Markdown with X-Respond-With: markdown.
409Result not ready / conflictOn a result read, poll the existing job until it completes. For other endpoints, resolve the conflict described in the body.
410Result expiredUse a saved copy. Retrying the result URL cannot restore an expired result.
422Invalid input / failed jobFix the reported fields. On a result read, inspect job.error: a failed job has no successful result to fetch.
429Limit reachedWait for Retry-After or retry_after. Reduce request rate; for a full pending queue, wait for existing jobs to finish.
500 / 502 / 503 / 504Service or upstream failureRetry 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.

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

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

SituationNext action
Invalid input, key, permission or balanceStop. Fix the request or account state before retrying; do not loop on these errors.
429 with a wait hintHonor 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 errorRetry the same GET. Without a wait hint, use increasing delays with jitter, a maximum attempt count and a time limit.
POST timeout or ambiguous 5xxKeep 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.statusWhat to do
pending / processingWait, then poll the same job. A result read returns 409 until completion.
completedRetrieve and save the result. Original JSON results return a 302 storage redirect; formatted results return a body directly.
failedStop polling and inspect job.error. The result endpoint returns 422 with code result_not_ready for a failed job.
Read job status · cURL / 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'

Response-format errors

Status / codeFix
400 · unsupported_representationSet X-Respond-With to markdown, or remove the header.
406 · not_acceptableSet 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.