19. 502 - engine unreachable

The service received the request but could not reach your instance. It is almost always transient - typically your instance is briefly unreachable while it restarts: a planned config change, a rolling engine deploy, or a writer changeover in an active-passive pair.

The official SDKs auto-retry on 502 with exponential backoff. If you're calling REST directly, you should too.

Any request that lands in that window - a restart, a deploy, or a writer changeover.

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT id FROM shop.products LIMIT 1"}'

{
  "error": "engine_unreachable",
  "message": "control plane could not reach the engine for this tenant",
  "retry": true,
  "trace_id": "5f4e3d2c-1b0a-9988-7766-554433221100",
  "status_page": "https://status.originchain.ai"
}

• Retry with exponential backoff. These windows are normally short; anything longer will show on the status page.
• If you're on an SDK, the retry happens automatically - you'll usually only see the 502 in logs as a warning, not as a thrown error.
• Check status.originchain.ai if retries keep failing for more than a minute.
• For non-idempotent writes, prefer OCC or a deduping pattern so a retried request doesn't double-apply.
• retry: true - this is the canonical "retry me" error.