Asynchronous Responses Handling (202 Accepted)

When to Return 202 Accepted

202 Accepted is an exceptional case and should only be used when absolutely nx₹ecessary. The normal expectation is immediate responses (200 OK) even for multiple concurrent requests.

Return 202 Accepted only in exceptional circumstances when:

• Order processing requires additional time that cannot be handled synchronously (e.g., external third-party API calls that are slow or unreliable).
• Complex validation requires external system integration that may take significant time.
• Background processing is truly necessary and cannot be optimized for immediate response.

Do NOT use 202 Accepted for:

• Normal order processing that can complete within reasonable time.
• Multiple concurrent requests (your system should handle these synchronously).
• Standard validation or submission operations.
• Performance optimization (optimize your system instead).

Best Practice: Design your system to handle concurrent requests efficiently and return immediate 200 OK responses. Use 202 Accepted only as a last resort when synchronous processing is truly not feasible.

Response Format

HTTP Status: 202 Accepted

Response Body: Same as 200 OK response, but status may be pending

Headers:

· x-pch-digest: {signature} (required)

· Location: /posnext/orders/{orderId} (optional, recommended)

Example:

HTTP/1.1 202 Accepted
x-pch-digest: abc123def456...
Location: /posnext/orders/order-12345
Content-Type: application/json
 
{
  "status": "pending",
  "request_uid": "order-12345",
  "location_id": "loc-001",
  ...
}

Polling Behavior

After receiving 202 Accepted, PAR will:

1. Poll GET /posnext/orders/{orderId} at intervals.
2. Continue polling until:
   • Final status received (placed, errored, rejected)
   • Timeout reached (configurable)
3. Cache final order status.

Note: The pending status indicates the order is still being processed. Once processing completes, the status should change to placed (successful), errored (failed), or rejected (rejected).

Polling Flow

Some operations return 202 Accepted with a request_uid for polling:

Polling Best Practices

• Design for Immediate Responses: Your system should be designed to handle concurrent requests and return immediate 200 OK responses. Use 202 Accepted only in truly exceptional cases.
• Process Quickly: If using 202 Accepted, complete processing as soon as possible to reduce polling.
• Return Accurate Status: Always return current status, even if pending.
• Include Order Details: Include order details in GetOrder response.
• Set Reasonable Timeouts: If using 202 Accepted, ensure processing completes within expected timeframe.
• Optimize Before Using 202: Before using 202 Accepted, consider optimizing your system to handle requests synchronously.