Handling 406 Errors and Inconsistent Behavior in Async HTTP Request Blocks

Overview

When using Async HTTP Request blocks in Cortex Workflows, you might notice inconsistent behavior. such as requests occasionally passing, timing out, or returning:
406: Action <block> is not in paused status

This usually occurs when your external service calls the callback URL too early, before the Async HTTP Request block has fully transitioned into its paused state.

Why This Happens

Async HTTP Request blocks follow a specific lifecycle:

1. Cortex sends a request to your external service.

2. Your service immediately returns a 200 OK response to acknowledge receipt.

3. Cortex then moves the block into a paused state and waits for your service to call the callback URL once the asynchronous work is complete.

If your service calls the callback URL before the block is fully paused, Cortex will return a 406 error because it’s not yet ready to accept the callback.

Resolution

To prevent this race condition, add a short delay (about 2–5 seconds) in your external service between returning the initial 200 OK response to Cortex and making the callback request.

⚠️ The delay must be implemented in your external system or script, not within Cortex.
This ensures the Async HTTP Request block has time to fully pause before the callback is sent.

Example Implementation

Below is an example of how to correctly handle the pause and callback flow in your external service:

import time
import requests

def handle_request(callback_url, cortex_token):
    # Step 1: Return 200 OK to Cortex immediately
    print("Returning 200 OK to Cortex...")
    # (Your web framework handles this HTTP 200 response)

    # Step 2: Wait 2–5 seconds to allow Cortex to enter paused state
    time.sleep(3)  
    
    # Step 3: Call the callback URL once async work is complete
    headers = {
        "Authorization": f"Bearer {cortex_token}",
        "Content-Type": "application/json"
    }

    body = {
        "message": "Provisioning complete – sandbox environment created.",
        "response": {
            "env_id": "sandbox-abc123"
        },
        "status": "SUCCESS"
    }

    response = requests.post(callback_url, headers=headers, json=body)
    print(f"Callback sent. Cortex responded with: {response.status_code}")