Nov 20, 20265 min read

The Asynchronous Request-Reply Pattern for Long-Running APIs

When an API call takes longer than a client or load balancer will wait, return 202 Accepted with a status URL and finish the work in the background. How to design the status resource, polling, callbacks and expiry, with a Go example on Encore.

Illustration for The Asynchronous Request-Reply Pattern for Long-Running APIs

Load balancers, proxies and browsers give up on a request after somewhere between 30 and 120 seconds, and users give up much sooner. A report that takes four minutes to build cannot be a normal request and response.

The asynchronous request-reply pattern separates accepting the work from finishing it. This guide covers the HTTP contract, how to design the status resource and when to use callbacks, and builds a working Go version on a queue and a database.

How does the pattern work?

The client posts the request and the server answers 202 Accepted right away, with a Location header naming a status URL, as in the Azure Architecture Center description. The work runs in a background worker. The client polls the status URL, which reports a state such as queued, running, succeeded or failed, and when the state is final it either returns the result or redirects to it with 303 See Other.

RFC 9110 defines 202 as accepted for processing, with no guarantee about the outcome, which is why the status resource exists.

What should the status resource contain?

A job ID, the state, timestamps, a progress figure if one is cheap to compute, an error message on failure, and a link to the result on success. Store it in your database, not in memory, so any instance can answer a status request and a restart loses nothing. Include a Retry-After header on in-progress responses to tell clients how often to poll, and expire finished jobs after a retention period.

Should the client poll or get a callback?

Browsers and mobile apps poll, since they cannot receive requests. Poll every few seconds, backing off on long jobs. Server-to-server clients can pass a callback URL at creation, and the server then sends a webhook when the job finishes. Webhooks need signatures and retries, covered in outgoing webhook delivery, and clients should still be able to poll in case a callback is lost.

What about duplicates and failures?

Let clients send an idempotency key with the creating request so a retry after a timeout returns the existing job, as described in API idempotency keys. The worker must also be idempotent, because queues deliver at least once. Mark jobs failed after the final retry with a message the client can act on, instead of leaving them in running forever.

Async request-reply with Encore

Encore

Encore is a backend framework with built-in infrastructure, and the job table, the queue and the worker are declared in the same Go service. The Postgres database and Pub/Sub topic run locally under encore run and are provisioned in your AWS or GCP account on deploy.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

-- exports/migrations/1_create_jobs.up.sql CREATE TABLE jobs ( id TEXT PRIMARY KEY, state TEXT NOT NULL DEFAULT 'queued', result_url TEXT, error TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );
// exports/exports.go package exports import ( "context" "encore.dev/beta/errs" "encore.dev/pubsub" "encore.dev/storage/sqldb" "github.com/google/uuid" ) var db = sqldb.NewDatabase("exports", sqldb.DatabaseConfig{Migrations: "./migrations"}) type JobRequested struct { JobID string `json:"job_id"` } var Requested = pubsub.NewTopic[*JobRequested]("export-requested", pubsub.TopicConfig{ DeliveryGuarantee: pubsub.AtLeastOnce, }) type Accepted struct { JobID string `json:"job_id"` StatusURL string `json:"status_url"` } //encore:api public method=POST path=/exports func Create(ctx context.Context) (*Accepted, error) { id := uuid.NewString() if _, err := db.Exec(ctx, `INSERT INTO jobs (id) VALUES ($1)`, id); err != nil { return nil, err } if _, err := Requested.Publish(ctx, &JobRequested{JobID: id}); err != nil { return nil, err } return &Accepted{JobID: id, StatusURL: "/exports/" + id}, nil } type Status struct { State string `json:"state"` ResultURL *string `json:"result_url,omitempty"` Error *string `json:"error,omitempty"` } //encore:api public method=GET path=/exports/:id func Get(ctx context.Context, id string) (*Status, error) { var s Status err := db.QueryRow(ctx, `SELECT state, result_url, error FROM jobs WHERE id = $1`, id). Scan(&s.State, &s.ResultURL, &s.Error) if err != nil { return nil, &errs.Error{Code: errs.NotFound, Message: "no such job"} } return &s, nil } var _ = pubsub.NewSubscription(Requested, "build-export", pubsub.SubscriptionConfig[*JobRequested]{ Handler: func(ctx context.Context, m *JobRequested) error { // Only claim a job that is still queued, so a redelivery does not run it twice. res, err := db.Exec(ctx, `UPDATE jobs SET state = 'running', updated_at = now() WHERE id = $1 AND state = 'queued'`, m.JobID) if err != nil { return err } if res.RowsAffected() == 0 { return nil } // Build the export here, then record where it lives. _, err = db.Exec(ctx, `UPDATE jobs SET state = 'succeeded', result_url = $2, updated_at = now() WHERE id = $1`, m.JobID, "/downloads/"+m.JobID) return err }, MaxConcurrency: 5, })

Create returns the job ID and status URL right away, and Get answers from the database, so any instance can serve it, and each job appears in a trace from the request through the subscriber. The status URL goes in the response body here, and a gateway or client can map it to a Location header if you need strict HTTP semantics. The conditional UPDATE ... AND state = 'queued' makes redeliveries harmless.

A coding agent can add the job table, topic and worker as one change, test the whole create, poll and finish flow under encore run, and the deploy provisions the infrastructure.

Best fit: Go teams with exports, report builds or media processing that outlive a request and who want the job state in Postgres and the worker on Pub/Sub in their own cloud account.

Frequently asked questions

What is the asynchronous request-reply pattern?

The client sends a request, the server responds immediately with 202 Accepted and a URL for checking progress, and the work continues in the background. The client polls that URL, or receives a callback, and fetches the result when the status says it is done.

Which HTTP status codes does async request-reply use?

The initial call returns 202 Accepted with a Location header pointing at a status resource. The status endpoint returns 200 with a state while the job runs, and once finished either returns the result or redirects with 303 See Other to where the result lives.

When should you use polling and when callbacks?

Polling suits browser and mobile clients, which cannot receive inbound requests, and keeps the server simple. Callbacks via webhooks suit server-to-server integrations, where polling wastes calls, and they should carry a signature and be retried.

How do I build async request-reply with Encore?

Create a job row in Postgres, publish a Pub/Sub message with the job ID, return the ID from the first endpoint and let a subscription do the work and update the row. A second endpoint returns the job state by ID. Encore provisions the database and topic in your AWS or GCP account.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders