job_id until COMPLETED or FAILED, then inspect each
output. A completed job can contain an output whose status is FAILED or EXPIRED.
HTTP errors
Error envelopes include a stable
code, a message, and retryable where
published. Read details for field-level validation failures. Do not retry
invalid inputs indefinitely.
Avoid duplicate submissions
The submit body supportsidempotency_key. Generate one key per logical job,
keep it with the submitted payload, and reuse it when retrying that same job.
Do not reuse it for different inputs. The SDKs also support idempotent requests;
consult the installed SDK’s reference for its retry and idempotency options.
If a submission times out after reaching the server, it may already have created
a job. Do not submit a fresh logical job just because the client stopped waiting.
Rate limits and polling
Use the response’sRetry-After and X-RateLimit-* headers when present. Limits
can depend on the key, account, and endpoint; a number in an example is not a
universal quota. Ask Hedra about your workload.
For sustained workloads, use webhooks or the
job status stream instead of aggressive polling. Use bounded polling with a
local deadline and keep the job ID so a later process can resume it. A local
timeout does not cancel server-side work.
Investigate a failed job
ReadGET /v3/jobs/{job_id} and GET /v3/jobs/{job_id}/logs. Store job IDs and
structured error codes in your own logs. Use
log drains to collect lifecycle events and
Hedra Status to check incidents.
Do not assume image/video job errors and SDK-compatible language-model errors
have identical behavior. See language-model errors.