How should an API gateway handle retries without accidentally creating duplicate MiniMax H3 video jobs?

An API gateway should handle retries for MiniMax H3 video creation by treating every create-video request as a side-effecting asynchronous job request: require an idempotency key, atomically bind that key to one canonical job record, submit the upstream create request only when the key is not already reserved, persist the upstream job ID and status when available, and return the stored job record on repeat attempts instead of creating another video job.

Short answer: never blindly retry a create-video request

The safest default is simple: do not blindly retry a create-video request after a timeout, 502, 503, 504, gateway timeout, or client disconnect. Those failures do not always mean the upstream provider failed to receive the request. They may mean the gateway lost visibility after the request was already accepted.

For asynchronous video generation, that difference matters. A second create request can allocate a second job, consume additional budget, create duplicate artifacts, and make downstream workflow state harder to reconcile. The gateway should therefore distinguish between:

• A first create attempt that has no existing idempotency record.
• A duplicate retry for the same tenant, user, payload, model or job type, and idempotency key.
• An ambiguous outcome where the gateway sent the request but did not receive or persist a final upstream response.

A production-ready gateway should not rely only on client behavior. Clients can retry after mobile disconnects, browser refreshes, worker crashes, queue redelivery, SDK timeout handling, or user-driven “try again” actions. The gateway is the control point that can enforce one canonical job per logical request.

In practice, the gateway should require a client-generated idempotency key for create-video calls, or compute a controlled key from a normalized payload when that fits the application. It should store that key durably before the upstream call and use atomic storage semantics so concurrent requests cannot create more than one upstream job.

Why duplicate MiniMax H3 jobs happen after timeouts and gateway failures

Duplicate video jobs usually happen in the gap between “the gateway does not know what happened” and “the application retries as if nothing happened.” With asynchronous job APIs, the create call initiates work that continues after the initial HTTP exchange. If the gateway times out after forwarding the request, the upstream service may still have accepted the job even though the client never received a job ID.

A typical duplicate sequence looks like this:

1. A client sends a create-video request through the API gateway.
2. The gateway forwards the request upstream.
3. The upstream service accepts the job, but the response is delayed, dropped, or not persisted by the gateway.
4. The gateway returns a timeout or transient failure to the client.
5. The client retries the same logical request.
6. The gateway forwards a second create request.
7. Two upstream jobs may now exist for one user intent.

The risky point is not polling, status checking, or downloading a completed asset. The risky point is replaying a create operation that may already have been accepted.

This is especially important for video generation because the unit of work is often expensive, slow-running, and visible to users or creative workflows. Duplicate jobs may not be obvious immediately. They may show up later as unexpected usage, duplicate output assets, inconsistent job status pages, or mismatched billing attribution.

The gateway needs to answer a practical operating question: “Have we already created or possibly created a job for this exact logical request?” If the answer is yes or unknown, the next action should be lookup or reconciliation, not another create submission.

Separate create calls from polling, status, and download calls

A strong retry design starts by classifying API operations by side effect. Treating every HTTP request the same is how duplicate work gets introduced.

For a MiniMax H3-style asynchronous video workflow, gateway policy should separate operations into at least two categories:

• Create-job operations: requests that can allocate new upstream work, consume quota, start rendering, or create a new task record.
• Read-like operations: requests that check status, poll progress, retrieve metadata, or download an existing result.

Create-job operations need strict idempotency and durable state. Polling, status, read, and download calls are generally safer retry candidates when they do not create new upstream work. They can usually tolerate bounded retries because repeating a read-like operation should not create an additional job. The gateway should still use backoff, rate limits, and timeout controls, but the duplicate-job risk is different.

A practical gateway retry matrix might look like this:

Operation type	Default retry posture	Main risk	Gateway control
Create video job	Do not blindly retry	Duplicate upstream job	Idempotency key, durable reservation, canonical job record
Poll job status	Retry with bounds	Excess traffic or rate pressure	Backoff, jitter, rate limits
Read job metadata	Retry with bounds	Stale or unavailable response	Cache policy, retry budget
Download result	Retry with bounds	Bandwidth pressure or partial download	Range handling where supported, bounded retries

The exact provider API design should always be reviewed before finalizing policy. The architectural principle remains: the gateway should apply stricter controls to any call that can create work than to calls that only observe existing work.

Use an idempotency key to map each request to one canonical job

The core pattern is gateway-side idempotency. The gateway should map one logical create request to one canonical job record, then use that record to answer duplicate retries.

A reliable flow typically looks like this:

1. Validate the request. Confirm tenant, user, authorization, payload shape, media references, and requested model or job type before reserving work.
2. Accept or compute an idempotency key. Prefer a client-generated key for user intent, such as one key per “generate this video” action. In some systems, the gateway may compute a key from a normalized payload, but that can be less expressive when the same user intentionally submits identical jobs.
3. Bind the key to a request fingerprint. Store the tenant, user, normalized payload hash, model or job type, media references, and any workflow identifier used to define the logical request.
4. Atomically reserve the key. Use a unique constraint, atomic insert, compare-and-set operation, distributed lock, or equivalent mechanism so two concurrent requests cannot both win.
5. Submit the upstream create request once. Only the request that successfully reserved the key should initiate the upstream job.
6. Persist the upstream job ID and status. Once the provider returns a job identifier or equivalent handle, store it with the idempotency record.
7. Return the stored job on duplicate retries. If another request arrives with the same key and matching fingerprint, return the existing canonical record instead of sending another create.

The idempotency key should not be treated as a loose label. It should be tied to the same tenant, user, normalized payload, model or job type, and relevant input assets. If the same key appears with a different payload, the gateway should reject the request, flag it for investigation, or return a clear conflict response depending on application policy.

This protects against a common failure mode: a client accidentally reuses a key for a different request. Without fingerprint binding, the gateway might return an unrelated job or hide an application bug. With fingerprint binding, the gateway can detect that the same key no longer represents the same logical work.

The canonical job record should be the source of truth for the application. It can include fields such as gateway request ID, idempotency key, tenant, user, normalized fingerprint, upstream job ID when known, gateway-side status, retry count, timestamps, and reconciliation notes. These are gateway-side implementation details, not assumptions about any specific provider schema.

Handle ambiguous outcomes as pending, not as permission to create again

The hardest retry case is not a clear upstream rejection. It is the ambiguous outcome: the gateway forwarded the create request, but the connection failed, the gateway timed out, the client disconnected, or the response was not durably persisted.

In that case, the gateway should not immediately issue another create request. It should mark the job record as pending or unknown and move into reconciliation.

A useful gateway-side state model may include:

• Reserved: the idempotency key has been accepted, but the upstream create request has not yet been sent.
• Submitted: the create request has been sent upstream.
• Unknown: the gateway cannot confirm whether upstream accepted the job.
• Succeeded: a canonical upstream job ID or completed result is known.
• Failed: the request failed in a way that policy treats as safe to surface or retry through a controlled path.
• Reconciled: an ambiguous state has been resolved through lookup, polling, logs, or operator review where available.

The important rule is that “unknown” is not the same as “safe to retry.” Unknown means the gateway has lost certainty. Creating another upstream job may solve the user-facing timeout quickly, but it can also create duplicate work and cost exposure.

Reconciliation depends on the provider and the system design. In many production gateways, possible recovery paths include polling by a stored upstream handle if one exists, checking gateway logs, reviewing provider-side activity if available, consulting asynchronous callbacks if the integration uses them, or using an operator-controlled recovery path for high-value jobs. If none of those can conclusively determine the outcome, the application may need to return a pending status to the user rather than automatically creating another job.

The user experience should reflect this state clearly. Instead of showing a generic failure and encouraging repeated submissions, the application can show that the video generation request is being verified. That small product decision can prevent many duplicate jobs.

Production retry controls: backoff, jitter, locks, and payload fingerprints

Idempotency is the foundation, but it is not the whole retry strategy. Production gateways also need bounded retry behavior so transient failures do not become retry storms.

For create-video requests, the retry policy should be conservative:

• Retry only when the gateway can prove it has not submitted the upstream create request, or when a durable idempotency record ensures only one canonical job can exist for the logical request.
• Do not retry indefinitely.
• Use exponential backoff with jitter for transient network or upstream availability failures.
• Apply retry budgets so one tenant, user, queue, or workflow cannot consume excessive capacity during an incident.
• Use rate limits and circuit breakers when upstream errors rise.
• Queue or shed load deliberately rather than allowing uncontrolled concurrent retries.

Concurrency control is equally important. Two identical requests can arrive at nearly the same time: a user double-clicks, two workers process the same queue message, or a client retry races with the original request. The gateway should use atomic database operations or locking so only one request can reserve the idempotency key.

Common implementation patterns include:

• A database table with a unique constraint on tenant plus idempotency key.
• An atomic insert that succeeds for the first request and fails for duplicates.
• A compare-and-set update for state transitions.
• A distributed lock when multiple gateway instances may process the same key and the storage layer does not provide enough atomicity on its own.
• A durable queue that preserves a single canonical work item per idempotency key.

Payload fingerprinting closes another gap. The fingerprint should represent the normalized request, not incidental formatting differences. Depending on the application, it may include prompt text, structured generation options, model or job type, input asset references, tenant, user, workspace, and workflow ID. If the idempotency key matches but the fingerprint differs, the gateway should treat it as a conflict rather than silently creating or returning the wrong job.

The gateway should also classify errors. A validation error, authorization failure, unsupported media reference, or malformed request is not a transient condition. Retrying those automatically adds noise. By contrast, a network timeout before any upstream submission, a temporary connection failure, or a short-lived gateway dependency issue may be retryable if the idempotency state confirms that no duplicate job can be created.

What to measure in the gateway and how Token Forge Cloud supports the serving layer

Duplicate prevention is only reliable when it is observable. The gateway should generate enough telemetry to reconstruct what happened for each create request, especially when the result is ambiguous.

Useful operating metrics include:

• Idempotency-key hit rate: how often retries are resolved by returning an existing canonical job.
• Unknown-outcome count: how often the gateway cannot confirm whether a create request succeeded.
• Retry count by status code or failure class: where retries are coming from and whether policy is too aggressive.
• Idempotency-key collision rate: how often the same key appears with a different fingerprint.
• Upstream job creation count: how many create requests are actually sent to the provider.
• Reconciliation latency: how long unknown states take to resolve.
• Suspected duplicate cost exposure: estimated usage tied to duplicate-risk incidents or unresolved ambiguity.
• Tenant-level retry pressure: which tenants, applications, or workflows generate the most retry load.

Logs should connect the full chain: idempotency key, gateway request ID, tenant, user, request fingerprint, upstream job ID when available, status transitions, retry count, timeout events, and reconciliation actions. Without these links, teams may see higher usage without knowing whether it came from legitimate demand, client retry behavior, queue redelivery, or duplicate job creation.

This is where the problem becomes a serving-layer control issue, not just an HTTP implementation detail. Enterprises using model APIs need routing, policy-aware access, usage visibility, and telemetry that make model consumption governable across teams and workloads.

Token Forge Cloud is designed around that serving-layer perspective. Token Forge Cloud Managed Model APIs provide an API-first entry point for teams that want model access, usage data, and a path into private deployment once workloads become predictable. Token Forge Cloud Private LLM Inference supports the broader control-plane conversation for organizations evaluating private deployment, routing policies, telemetry, and inference cost control.

For teams working with video generation, chat, batch enrichment, agentic workflows, or other model-driven applications, the same operating discipline applies: classify side effects, control retries, measure usage, and keep enough state at the serving layer to make failures recoverable. Token Forge Cloud treats different workload types as different serving-policy problems, which supports retry behavior, observability, and cost governance.

When evaluating gateway behavior for MiniMax H3 or any asynchronous model API, leaders should ask:

• Does the gateway enforce idempotency for create-job operations?
• Can it distinguish create, poll, read, and download calls?
• Are ambiguous outcomes persisted as pending or unknown rather than retried blindly?
• Are idempotency keys bound to tenant, user, payload fingerprint, and job type?
• Can operations teams trace a request from client action to upstream job ID?
• Can finance and platform teams see duplicate-risk exposure and retry-driven usage?
• Is there a path from managed API access to more controlled deployment as workloads become predictable?

Contact Token Forge Cloud to discuss API access, private deployment, and LLM inference cost control.