Loading documentation…
Loading documentation…
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": {"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}}}
INVALID_REQUESTThe request body failed validation. Check the required fields and data types.
INSUFFICIENT_DATAToo few symptoms or evidence items provided for a meaningful assessment. Provide at least 1 symptom with "present" choice.
INVALID_API_KEYThe API key is missing, malformed, or has been revoked. Check the Authorization header.
QUOTA_EXCEEDEDYour monthly assessment quota has been exceeded. Upgrade your plan or wait for the next billing cycle.
RESOURCE_NOT_FOUNDThe requested endpoint or resource does not exist. Verify the URL and version prefix.
RATE_LIMIT_EXCEEDEDRetryableYou have exceeded 100 requests per minute. Implement exponential backoff.
INTERNAL_ERRORRetryableAn unexpected error occurred. The incident has been logged. Retry with exponential backoff.
AI_PROVIDER_UNAVAILABLERetryableThe AI reasoning engine is temporarily unavailable. The health endpoint (/v1/health) will reflect degraded status.
For retryable errors (429, 500, 503), implement exponential backoff with jitter:
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 jitterconst delay = Math.pow(2, attempt) * 1000;const jitter = Math.random() * 1000;await new Promise(r => setTimeout(r, delay + jitter));}}}
Design your integration to handle API downtime gracefully:
After 5 consecutive failures, stop calling the API for 60 seconds. Check /v1/health before resuming.
Show a "manual triage" form when the API is unavailable. Collect patient data and retry when the service is restored.
Cache condition and symptom data from /v1/conditions and /v1/symptoms. These change infrequently and can be served from cache.
Poll GET /v1/health every 30 seconds. If status is "degraded" or "unhealthy", proactively warn users.