Error handling

Every Symptom & Illness Check API error tells you two things — whether you can fix it (customType) or whether something failed on XUND's side (details.errorCode) — and handling that distinction correctly covers most of what an integrator needs. This page is the single reference for the error body shape, the authentication rules, the error codes, and retry guidance.

The error response shape

Errors are JSON bodies with up to three fields:

{
  "error": "Forbidden",
  "customType": "OVERVIEW_CAN_NOT_BE_SKIPPED",
  "details": {
    "description": "It is not possible to confirm the overview without getting it"
  }
}

The set of customType values is open: new codes can appear without prior notice, so treat any unknown code generically (log it, show a generic error) rather than failing hard.

Authentication errors

Every request authenticates with an authorization: Bearer <token> header — see Authentication for obtaining tokens.

Tokens expire, and there is no refresh-token flow for the client-credentials grant — on INVALID_TOKEN, request a fresh token from the token endpoint described in Authentication and repeat the request. A robust integration treats any 401 as "re-authenticate, then retry once".

Error codes

The most common codes, what triggers them, and how to react. Statuses: codes in the check-lifecycle and flow groups are 400 unless noted.

Initialization failures and other 500s

A 500 body has no customType; instead details.errorCode carries an internal code (usually XAG-prefixed). Two initialization cases are worth knowing:

• Symptom check (initializeSymptomCheck): if even one provided FHIR observation's UMLS code cannot be mapped to a XUND symptom, the request fails with status code 500. An unknown mainSymptomId, by contrast, is a 400 (INITIALIZER_SYMPTOM_NOT_FOUND).
• Illness check (initializeIllnessCheck): if the FHIR condition's ICD-10 code is not known to the Content Library, the request fails with status code 500.

Retry guidance

The rule of thumb: 4xx means your request is wrong — fix it, don't resend it unchanged; 5xx means something failed on XUND's side — retrying an idempotent request is reasonable.

• Safe to retry: all GET endpoints (question, status, overview, report, lookups). Their responses stay consistent across calls, so retrying after a timeout or 5xx is harmless — but note they are not all stateless: the first GET /v1/chatbot/report (or /report/pdf) finalizes the check; retrying it simply serves the same report from the now-closed check.
• Not safe to retry blindly: PATCH /v1/chatbot/overview/answer/batch. It is applied sequentially and non-atomically — after a 500, some of the edits are already in place, so re-sending the same payload can fail again or re-apply edits. Re-read the check's state (for example GET /v1/chatbot/status) and send only what is still missing.
• Retry after re-authenticating: a 401 is not a transient failure; get a fresh token first (see above).
• Escalate instead of retrying: a 4xx with a customType will keep failing until the request changes. A persistent 5xx with the same errorCode is a bug or content issue on XUND's side — report it with the errorCode and, where relevant, the check-id.