Error Handling

All API errors return a consistent JSON structure with an error code, human-readable message, and optional details. This guide covers every error code, when to retry, and patterns for graceful degradation.

Error Response Format

json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Max 100 requests per minute.",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset": "2026-03-01T12:01:00Z",
      "retryAfter": 42
    }
  }
}

Error Codes Reference

400INVALID_REQUEST

The request body failed validation. Check the required fields and data types.

400INSUFFICIENT_DATA

Too few symptoms or evidence items provided for a meaningful assessment. Provide at least 1 symptom with "present" choice.

401INVALID_API_KEY

The API key is missing, malformed, or has been revoked. Check the Authorization header.

403QUOTA_EXCEEDED

Your monthly assessment quota has been exceeded. Upgrade your plan or wait for the next billing cycle.

404RESOURCE_NOT_FOUND

The requested endpoint or resource does not exist. Verify the URL and version prefix.

429RATE_LIMIT_EXCEEDEDRetryable

You have exceeded 100 requests per minute. Implement exponential backoff.

500INTERNAL_ERRORRetryable

An unexpected error occurred. The incident has been logged. Retry with exponential backoff.

503AI_PROVIDER_UNAVAILABLERetryable

The AI reasoning engine is temporarily unavailable. The health endpoint (/v1/health) will reflect degraded status.

Retry Strategy

For retryable errors (429, 500, 503), implement exponential backoff with jitter:

javascript
async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (!error.retryable || attempt === maxRetries - 1) throw error;

      // Exponential backoff: 1s, 2s, 4s + random jitter
      const delay = Math.pow(2, attempt) * 1000;
      const jitter = Math.random() * 1000;
      await new Promise(r => setTimeout(r, delay + jitter));
    }
  }
}

Graceful Degradation

Design your integration to handle API downtime gracefully:

Circuit Breaker

After 5 consecutive failures, stop calling the API for 60 seconds. Check /v1/health before resuming.

Fallback UI

Show a "manual triage" form when the API is unavailable. Collect patient data and retry when the service is restored.

Cache Responses

Cache condition and symptom data from /v1/conditions and /v1/symptoms. These change infrequently and can be served from cache.

Monitor Health

Poll GET /v1/health every 30 seconds. If status is "degraded" or "unhealthy", proactively warn users.

Related Resources

API Reference — full endpoint documentationAuthentication — API key format & rate limits
EndpointsVersioning