agent-media Developers
Jobs, errors and retries
Recover the original request instead of accidentally generating twice.
On this page
Keep request identity and job IDs
For MCP generate_image, generate_video and generate_audio, pass request_id. For POST /v2/generate/:kind, send the Idempotency-Key header. Generate a fresh identity for each intended generation and save it with the exact inputs before submitting. Reuse both after a lost response. A retry returns the original job without another debit; changed inputs under the same identity return HTTP 409. This protection does not cover every fixed recipe.
An uncertain acknowledgement
If a generation response returns an accepted job but says worker acknowledgement is uncertain, poll that job. Do not infer failure or assume a refund.
Temporary status failures
HTTP 503 STATUS_UNAVAILABLE means status could not be read. Respect Retry-After and retry the original job ID. HTTP 404 after an authenticated, successful lookup means the job was not found for that account.
Temporary account failures
HTTP 503 ACCOUNT_CHECK_UNAVAILABLE means the balance is unknown. Retry the check; do not treat it as zero. Quotes and balance snapshots do not reserve credits or guarantee provider availability.
Report confirmed outcomes
Provider and generation failures should be reported with their actual error and job ID. Only tell a user that credits were refunded when the service confirms it.