HTTP Status 202 (Accepted)

HTTP Status 202 (RFC-7231) indicates that the request has been accepted for processing, but the processing has not been completed. This status code is useful when the actual operation is asynchronous in nature.

The purpose of HTTP 202 is to allow a server to accept a request for some other process (such as a batch-oriented process that is only run once per day or a long-running REST API) without requiring that the user agent’s connection to the server persist until the process is completed.

1. HTTP Status 202 Response Body

The HTTP status code 202 falls into the 2xx series, which typically indicates successful responses. However, the “Accepted” response is distinct in that it doesn’t signify the immediate success of a request. Instead, it informs the client that the request has been accepted for processing but hasn’t necessarily been acted upon or completed yet.

The HTTP 202 status code is used in scenarios where immediate processing of a request isn’t possible, and the client should be aware that the request will be handled asynchronously.

The entity returned with this response SHOULD describe the request’s current status and point to (or embed) a status monitor that can provide the user with (or without) an estimate of when the request will be fulfilled.

POST /api/tasks

Status: 202 Accepted
Location: /tasks/12345
Content-Type: application/json

{
  "taskId": 12345,
  "status": "pending",
  "createdAt": "2023-11-04T10:00:00Z"
}

2. HTTP Status 202 Example

The 202 response is often used in conjunction with mechanisms for handling asynchronous processing, such that the client periodically checks the status of the request until it’s completed. We can use real-time communication channels (e.g. WebSockets) are used to provide updates on the request’s progress.

Ifn the following example, we submit a long-running asynchronous job to a REST API and the API can return the result like this:

HTTP STATUS 202 (Accepted)

{
	"task": {
		"href": "/api/company/job-management/jobs/2130040",
		"id": "2130040"
	}
}

Now user agent can send HTTP GET requests to URI ‘/api/company/job-management/jobs/2130040‘ periodically for the completion status of the job.

The response of the above API will inform the current status of the actual scheduled operation.

2.1. Job Not Started

{
	"job" : {
		"@uri" : "/api/company/job-management/jobs/2130040" ,
		"id" : "2130040",
		"name" : "Update Resource",
		"job-state" : "SCHEDULED",
		"job-status" : "UNDETERMINED",
		"percent-complete" : "0",
		"scheduled-start-time" : "01-01-2013 10:50:45 PM GMT",
		"start-time" : "",
		"end-time" : "",
		"owner" : "Admin",
		"summary" : "random text"
	}
}

2.2. Job Started

{
	"job" : {
		"@uri" : "/api/company/job-management/jobs/2130040" ,
		"id" : "2130040",
		"name" : "Update Resource",
		"job-state" : "STARTED",
		"job-status" : "INPROGRESS",
		"percent-complete" : "30",
		"scheduled-start-time" : "01-01-2013 10:50:45 PM GMT",
		"start-time" : "01-01-2013 10:50:55 PM GMT",
		"end-time" : "",
		"owner" : "Admin",
		"summary" : "random text"
	}
}

2.3. Job Completed

{
	"job" : {
		"@uri" : "/api/company/job-management/jobs/2130040" ,
		"id" : "2130040",
		"name" : "Update Resource",
		"job-state" : "COMPLETED",
		"job-status" : "SUCCESS",
		"percent-complete" : "100",
		"scheduled-start-time" : "01-01-2013 10:50:45 PM GMT",
		"start-time" : "01-01-2013 10:50:55 PM GMT",
		"end-time" : ""01-01-2013 10:52:18 PM GMT",
		"owner" : "Admin",
		"summary" : "random text"
	}
}

The above example is for reference only.

3. Best Practices

When using HTTP 202, it’s important to follow these best practices:

• Provide a way for the client to monitor the progress or receive the result of the request.
• Include relevant headers, such as ‘Location‘, to indicate where the client can obtain more information about the request’s status.
• Clearly document the expected behavior and handling of the request, including any time limits for polling or callbacks.

Happy Learning !!