Maintenance Mode

IBEX FI API – Maintenance Mode (Client Guide)

This guide explains what your application will observe through IBEXFIAPI when maintenance is active. It focuses solely on what the IBEXFIAPI interface returns over HTTP and WebSocket (WS). Clients never call downstream services directly.

Quick summary

• Affected HTTP endpoints return 503 Service Unavailable with a stable JSON body.
• Affected WebSocket requests receive a structured maintenance message instead of normal data.
• When maintenance starts or ends, IBEXFIAPI can broadcast WS notifications so clients can adapt UI/flows.
• Use exponential backoff and avoid tight, parallel retry loops.

A) IBEXFIAPI maintenance (global)

When the main API is under maintenance, non-health endpoints temporarily stop normal processing.

HTTP behavior

• Status: 503 Service Unavailable
• Body example:

{
  "status": "maintenance",
  "service": "IBEXFIAPI",
  "since": "2025-08-25T08:52:36.000Z",
  "message": "The service is undergoing maintenance. Please retry later."
}

• Health endpoint (/health) may still reply 200 for liveness; do not treat it as readiness for feature traffic.

WebSocket behavior

• New or in-flight feature requests may receive a maintenance message or be temporarily rejected.
• Message example:

{
  "type": "maintenance",
  "service": "IBEXFIAPI",
  "active": true,
  "since": "2025-08-25T08:52:36.000Z",
  "message": "The service is undergoing maintenance. Please retry later."
}

• On exit (broadcast):

{
  "type": "maintenance",
  "service": "IBEXFIAPI",
  "active": false,
  "endedAt": "2025-08-25T09:05:12.000Z",
  "message": "Maintenance ended. Normal operations resumed."
}

B) BCReader-related maintenance (as observed via IBEXFIAPI)

When the BCReader integration is under maintenance, only endpoints and WS actions that depend on it are impacted. Other API features remain available.

Impacted HTTP endpoints

• Affected routes: GET/POST /v1.2/bcreader/:verb (IBEXFIAPI proxy endpoints)
• Response:
  • Status: 503 Service Unavailable
  • Body example:

{
  "status": "maintenance",
  "service": "BCREADER",
  "since": "2025-08-25T08:52:36.000Z",
  "message": "BCReader-dependent features are temporarily unavailable. Please retry later."
}

Impacted WebSocket actions

• Typical actions: balance/transaction lookups such as getBalance, getTransaction.
• Response example:

{
  "type": "maintenance",
  "service": "BCREADER",
  "active": true,
  "since": "2025-08-25T08:52:36.000Z",
  "message": "BCReader-dependent features are temporarily unavailable. Please retry later."
}

• On exit (broadcast):

{
  "type": "maintenance",
  "service": "BCREADER",
  "active": false,
  "endedAt": "2025-08-25T09:05:12.000Z",
  "message": "BCReader-dependent features restored."
}

Notes:

• The examples above show representative payloads. The exact field set may include additional context fields (e.g., a requestId).

Client recommendations

• Detect 503 and WS \{ type: "maintenance" \} messages and degrade gracefully (e.g., show a banner or toast).
• Implement exponential backoff with jitter (e.g., 10s → 20s → 40s, up to ~5min) for retries.
• Avoid retrying multiple identical requests in parallel during maintenance.
• Consider displaying last known data (with a clear "might be outdated" label) while maintenance is active.
• For WS, you may keep the connection open and quietly reduce request frequency until maintenance ends.

Examples (copy/paste)

HTTP – Example request during maintenance (BCReader-related route)

Request:

curl -i \
  -H "Authorization: Bearer <token>" \
  "https://<host>/v1.2/bcreader/transactions?address=0x...&chainId=100"

Response:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
 
{"status":"maintenance","service":"BCREADER","since":"2025-08-25T08:52:36.000Z","message":"BCReader-dependent features are temporarily unavailable. Please retry later."}

WS – Example request during maintenance (getBalance)

Client message:

{"action":"getBalance","address":"0x...","chainId":100}

Server response:

{"type":"maintenance","service":"BCREADER","active":true,"since":"2025-08-25T08:52:36.000Z","message":"BCReader-dependent features are temporarily unavailable. Please retry later."}

If you need details about how maintenance is toggled operationally, contact IBEX support. This document focuses on what your application receives from IBEXFIAPI during maintenance windows.