Async Operations Guide

How to work with GoTamil API’s automatic sync/async routing and implement robust polling.

When Does Async Happen?

The API automatically routes to async processing when:

1. Text length exceeds 1200 characters (SYNC_TEXT_THRESHOLD)
2. Client preference — Prefer: respond-async header is set
3. Sync timeout — processing exceeds 8 seconds (SYNC_TIMEOUT_MS)

Detecting Async Responses

Check the HTTP status code:

Polling Pattern

# 1. Submit request
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$GOTAMIL_API/v1/proofread" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "long tamil text...", "language": "ta"}')
 
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | head -1)
 
# 2. If async, poll
if [ "$HTTP_CODE" = "202" ]; then
  OP_ID=$(echo "$BODY" | jq -r '.operation_id')
 
  while true; do
    POLL=$(curl -s "$GOTAMIL_API/v1/operations/$OP_ID" \
      -H "Authorization: Bearer $TOKEN")
 
    STATUS=$(echo "$POLL" | jq -r '.status')
 
    case "$STATUS" in
      succeeded|failed|cancelled) break ;;
    esac
 
    sleep 2  # exponential backoff recommended
  done
 
  echo "$POLL" | jq .
fi

Best Practices

Use Exponential Backoff

Don’t poll at a fixed interval. Start at 1-2 seconds and increase:

1s → 2s → 4s → 8s → 8s (cap)

Always Send Idempotency Keys

If your request might be retried (network issues, timeouts), always include an Idempotency-Key header. The API deduplicates by (tenant_id, endpoint, idempotency_key).

Handle All Terminal States

Your polling loop should handle all terminal states:

Force Async for Batch Operations

If you’re submitting many requests, use Prefer: respond-async to avoid holding connections open:

curl -X POST "$GOTAMIL_API/v1/proofread" \
  -H "Prefer: respond-async" \
  ...

Queue Backends