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.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.