Operações de longa duração: 202 Accepted e um recurso de status

O que é

A RFC 9110 (citada) define o 202 (Accepted) como intencionalmente não comprometedor: a requisição foi aceita para processamento, mas o processamento não terminou, ela ainda pode ser recusada depois, e o HTTP não tem nenhum mecanismo para reenviar um código de status de uma operação assíncrona. A representação enviada com um 202 deveria descrever o estado atual da requisição e apontar para um monitor de status (ou incorporá-lo). A AIP-151 do Google (citada) faz desse monitor um recurso de primeira classe: métodos que podem levar um tempo considerável retornam uma Operation com um nome, um indicador done, metadata para progresso e falhas parciais e, ao concluir, error ou response. A regra prática da AIP é que trabalhos acima de cerca de 10 segundos justificam o padrão e que as operações podem expirar, sendo 30 dias o prazo sugerido.

Por que importa

Manter uma conexão bloqueada por minutos falha em todas as camadas: proxies cortam conexões ociosas, clientes estouram o timeout e tentam de novo, e um job não idempotente repetido acaba executando duas vezes. Um recurso de operação explícito permite que o cliente se desconecte, faça polling e se recupere após o próprio reinício, e dá ao servidor um único lugar para registrar o resultado.

Como aplicar

• Retorne 202 Accepted com um Location (ou um link no corpo) para /operations/{id} e inclua a representação da operação no corpo, para que o cliente não precise fazer uma segunda requisição imediata.
• Modele a operação com done, metadata (progresso, contagens, erros não fatais) e exatamente um entre error ou response quando estiver concluída; use o mesmo formato de erro das falhas síncronas.
• Aceite uma chave de idempotência fornecida pelo cliente na requisição inicial, para que uma nova tentativa após a perda de um 202 retorne a mesma operação em vez de iniciar uma segunda.
• Suporte o polling com dicas via Retry-After; ofereça um webhook para clientes que consigam recebê-lo, mas mantenha o polling como alternativa.
• Documente a expiração: por quanto tempo o resultado continua acessível e o que um GET em uma operação expirada retorna.
• Para recursos criados de forma assíncrona, deixe List e Get exibirem o recurso com um estado que o marque como ainda não utilizável (AIP-151).
• Defina como se comportam operações paralelas sobre um mesmo recurso: enfileirá-las ou rejeitá-las com um erro de conflito que indique a operação em andamento.

Armadilhas

Retornar 202 e processar de forma síncrona mesmo assim. Alterar o tipo de resultado de uma operação existente, o que a AIP-151 lista como uma mudança incompatível. Usar 200 com um corpo "pending", o que faz caches e clientes tratarem o job como concluído. Perder os registros de operações ao reiniciar, de modo que o cliente nunca descobre o resultado. Expor endpoints de polling sem limites de taxa.

Responder de forma síncrona quando o trabalho é rápido

Quando a latência é bimodal, decida por requisição, e não por tipo de operação. Execute o job por um tempo limitado e, se ele terminar, responda 200 ou 201 com o resultado; caso contrário, responda 202 com o recurso de operação. A RFC 7240 dá voz ao cliente: Prefer: wait=N limita por quanto tempo ele aceita esperar, Prefer: respond-async pede diretamente o caminho do 202, e o servidor informa o que respeitou em Preference-Applied. Documente os dois formatos de resposta da operação e deixe o helper de espera do SDK normalizá-los, de modo que quem chama veja um único tipo de resultado. Reserve o design que sempre responde 202 para trabalhos que são sempre longos.