Skip to main content

Health

Overview​

Health endpoints allow you to confirm the API is reachable and responding.

Use these for monitoring and basic connectivity checks.

Health & Status Guide

Table of Contents​

  1. Overview
  2. Authentication
  3. Base URLs
  4. Health Check Endpoint
  5. Error Handling
  6. Best Practices
  7. Quick Reference
  8. Support

Overview​

The eFICA Health API provides a single endpoint used to confirm that the eFICA API is reachable and responding. This is typically used by:

  • Uptime monitors (e.g., UptimeRobot, Datadog, Pingdom)
  • Internal dashboards (to display “API Online/Offline”)
  • CI/CD pipelines (basic “is the API up?” checks)

Key Features​

  • Public access: no authentication required
  • Lightweight: designed for frequent polling
  • Stable response: returns a simple JSON response

What “healthy” means (important)​

When the endpoint returns 200 OK and { "status": "ok" }, it means:

  • the API server is running, and
  • the API can accept and process requests.

It does not guarantee that every downstream dependency is healthy (e.g., database, third‑party services). Your monitoring strategy should include:

  • this endpoint (API process + routing), and
  • your own business-critical checks (e.g., “can we create a customer portal link?”) if required.

Authentication​

No authentication required.

This endpoint is intentionally public so monitoring systems do not need to manage OAuth2 tokens.

All other public API endpoints require OAuth2 authentication. See: OAuth2 PKCE Integration Guide

Base URLs​

  • Sandbox: https://sandboxapi.efica.co.za
  • Production: https://loginapi.efica.co.za

API Version​

The health endpoint is available under:

  • GET /api/v1/health

Health Check Endpoint​

Check API health status​

Confirms the API is responding.

Endpoint: GET /api/v1/health
Authentication: None (public)

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/health"

Response Example:

{
  "status": "ok"
}

Response Fields:

  • status (string): health indicator. When the API is operating normally, this returns "ok".

HTTP Status Codes:

  • 200 OK: API is responding normally
  • 500 Internal Server Error: API encountered an unexpected error

Error Handling​

Although the health endpoint is simple, you should still handle errors cleanly in monitoring tools and client code.

Standard Responses​

Status CodeMeaningTypical Cause
200OKAPI is running and responding
500Internal Server ErrorAPI is down, restarting, or unhealthy

Error Response Format​

If an error occurs, the API may return a standard error payload like:

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Best Practices​

1. Polling Frequency​

  • Production uptime monitoring: every 1–5 minutes

Avoid very aggressive polling from many locations (it adds load with no benefit).

2. Timeouts​

Always set a timeout so your monitors don’t hang indefinitely:

  • Recommended: 3–10 seconds

3. Alerting (reduce false alarms)​

Do not alert on a single failure. Instead:

  • alert after 2–3 consecutive failures
  • use different severities for short outages vs sustained outages

4. Simple Integration Example (JavaScript)​

async function checkEficaHealth(baseUrl) {
  const resp = await fetch(`${baseUrl}/api/v1/health`, { method: "GET" });
  if (!resp.ok) return { healthy: false, status: resp.status };
  const data = await resp.json();
  return { healthy: data?.status === "ok", data };
}

Quick Reference​

Endpoint Summary​

EndpointMethodAuthenticationDescription
/api/v1/healthGETNone (Public)Check API health

Full URLs​

  • Sandbox: https://sandboxapi.efica.co.za/api/v1/health
  • Production: https://loginapi.efica.co.za/api/v1/health

Quick Test​

curl "https://loginapi.efica.co.za/api/v1/health"

Support​

For questions about the Health endpoint:

Last Updated: 26 January 2026