Handle asynchronous AI API results without duplicates or false success
An accepted call does not mean its output is ready. Replicate documents a prediction lifecycle and webhooks that can repeat or arrive out of order. The method below is a proposed design to adapt to your API, not an integration executed in your account.
The method to apply
Separate requests, execution and accepted outputs. Associate events and files with stable identifiers, verify origin before processing and make recovery idempotent. A completion notification can signal failure; it must not automatically create a successful deliverable.
- Origin
- Uniqueness
- State
- Output
Prepare, test and decide
1. Define application states
Write what the interface shows when a request is received, starting, processing, successful, failed or cancelled. Map the provider’s actual states instead of inventing one ‘finished’ state. Add a separate state for human output review.
2. Retain the right identifiers
Link business identifier, remote request, model and version. Outputs must return to the correct request even when several jobs finish simultaneously. Keep diagnostic parameters without exposing keys or private data in public logs.
3. Verify events before use
Use the signature mechanism documented for your API and check timestamps according to the provider’s method. Replicate documentation specifies the raw body: transforming it before verification can invalidate the check. Make no business changes from an unverified origin.
4. Resist duplicates and disorder
Record processed events and define transitions that cannot regress after a final state. Test duplicate notifications, a late intermediate event and concurrent processing. A non-atomic check followed by a write can create duplicates; examine that case too.
5. Check cancellation and output
A client-side timeout does not prove remote cancellation. Check actual state and provider cost conditions. For file outputs, check availability, format and authorised retrieval; a received URL is not a permanently archived file.
6. Test complete recovery
Simulate interruption after reception but before a business update. Replay the event and check that only one deliverable is produced. Logs should distinguish lost requests, rejected events, missing files and rejected outputs, allowing recovery without blindly repeating a paid generation.
Examine profiles related to this method
Put the method to work
Practical case
Fictional case: request A succeeds; its final event arrives twice; a processing event arrives later. Request B fails.
Evidence to keep
Expected: one deliverable for A, final state preserved, no successful deliverable for B and separate records for both requests.
Make the decision
Reject the flow if it duplicates output, regresses to processing or presents B as successful merely because completion was notified.
Acceptance criteria
Origin
Unverified events cause no business changes.
Uniqueness
Repeated events create no second deliverable.
State
Late notifications cannot overwrite final state.
Output
Technical success is distinct from deliverable acceptance.
Profiles related to this method
These profiles document relevant tools. Their order is not a performance ranking.
Codex
coding agent
OpenAI · US
Visit official site
Dify
workflow building
LangGenius / Dify
Visit official site
OpenAI Platform
model APIs
OpenAI · US
Visit official site
LangGraph
agent development framework
LangChain · US
Visit official site
Claude Code
coding agent
Anthropic · US
Visit official site
LlamaIndex
agent development framework
LlamaIndex · US
Visit official siteHow is this selection produced?
Active services are distributed across guide-related categories, then ordered by editorial highlighting and internal score. This does not assess security, compliance or performance on your use case. Methodology.
Explore tools for this task
- OpenRouter — Compare models in one application while distinguishing their conditions.
- Groq — Evaluate inference service behaviour in an interactive application.
- Zed — Edit a selection or prepare a fix inside an editor.
- OpenCode — Explore a repository and propose a bounded change.
- CrewAI — Decompose a process into steps with explicit responsibilities.
- Langflow — Prototype a document workflow and inspect its steps separately.
Related tool families
Frequently asked questions
Does a completed webhook mean succeeded?
Not necessarily. In the consulted API, terminal states include failure and cancellation; inspect the precise value.
Can Replicate rules be used for every API?
No. Reuse the testing method but consult each provider’s signatures, states, retries and terms.
The references below expand on the concepts and checks discussed. Scenarios and trial frameworks remain editorial proposals; provider documentation describes its own product rather than an independent benchmark.
