draft-ratnawat-httpapi-async-problem-details

Problem Details for Asynchronous Job Failures

groupnone stateactive pages46 rev00 expires2026-09-02 canonicalhttps://datatracker.ietf.org/doc/draft-ratnawat-httpapi-async-problem-details/
HTTP APIs that process work asynchronously need a standard way to report job failures. "Problem Details for HTTP APIs" (RFC 9457) provides the envelope; this document defines extension members that fill it with asynchronous-job-specific context. Eight extension members are specified: "jobId", "jobStatus", "submittedAt", "completedAt", "retryable", "retryAfter", "processingStage", and "correlationId". A ninth member, "results", supports batch operations. Together they let a server describe which job failed, when, at what pipeline stage, and whether a retry is advisable -- in a single, machine-readable JSON (RFC 8259) object that works equally well in an HTTP response body, a message-broker payload, or a webhook callback. Although the primary motivation is structured error reporting for failed jobs, the extension members are equally useful for communicating successful job outcomes (e.g., a COMPLETED status with timing information). This document does NOT redefine how to submit, poll, or cancel asynchronous jobs; those mechanics are already covered by "HTTP Semantics" (RFC 9110) (202 Accepted), "Prefer Header for HTTP" (RFC 7240) (respond-async), and emerging IETF work on long-running operations. Instead, it focuses exclusively on the structured reporting gap that remains after a job reaches a terminal state.