Errors

Every JSON error has a stable machine-readable code and a human-readable message. Branch on code and the HTTP status; show or log message.

curl --include "$DOCTRONIC_API_URL/users/" \
  -H "Authorization: Bearer invalid-token"

{
  "code": "error.auth.unauthorized",
  "message": "Unauthorized."
}

Field validation failures return 400 with code set to error.validation_error and data set to a list of {field, message, code} entries. field is the request location and camelCase field path, separated by dots:

{
  "code": "error.validation_error",
  "message": "Validation error",
  "data": [
    {
      "field": "body.requiredField",
      "message": "Field required",
      "code": "error.validation.missing"
    }
  ]
}

HTTP status codes

The SDKs throw one error class per status, the same in TypeScript and Python. Each extends APIError, which carries status, code, message, data, and the request ID.

Some operations add their own statuses. GET /artifacts/{artifactId}/ returns 202 while a consultation document is still generating and 500 when generation failed permanently; see consultation documents.

Error code reference

Every error.* code in the OpenAPI contract. Codes are case-sensitive wire values.

The stream can also emit error.consultation_not_ready, described under stream errors.

Idempotent requests

Send an Idempotency-Key header on a mutation so a retry can't apply it twice. These operations accept one:

Generate one unique, opaque key (up to 255 characters) for each intended change. If the response is lost, retry the same method, path, and body with the same key:

IDEMPOTENCY_KEY="$(uuidgen)"

curl --include -X POST "$DOCTRONIC_API_URL/chats/" \
  -H "Authorization: Bearer $DOCTRONIC_API_TOKEN" \
  -H "X-Doctronic-User-ID: $DOCTRONIC_USER_ID" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/New_York"}'

const idempotencyKey = crypto.randomUUID();
const body = JSON.stringify({ timezone: 'America/New_York' });

async function createChat(): Promise<Response> {
  for (let attempt = 1; ; attempt += 1) {
    try {
      const response = await fetch(`${process.env.DOCTRONIC_API_URL}/chats/`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.DOCTRONIC_API_TOKEN}`,
          'X-Doctronic-User-ID': process.env.DOCTRONIC_USER_ID!,
          'Idempotency-Key': idempotencyKey,
          'Content-Type': 'application/json',
        },
        body,
        signal: AbortSignal.timeout(10_000),
      });
      if (response.status !== 503 || attempt === 3) return response;
      const retryAfter = Number(response.headers.get('retry-after') ?? '1');
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    } catch (error) {
      // Network failure or timeout: the outcome is unknown, so retry with the same key.
      if (attempt === 3) throw error;
      const backoff = 2 ** attempt * 500 + Math.random() * 250;
      await new Promise((resolve) => setTimeout(resolve, backoff));
    }
  }
}

const response = await createChat();
console.log(response.status, response.headers.get('idempotency-replayed'));

The API stores the result for 24 hours. A response served from that store includes:

Idempotency-Replayed: true

Use a key for exactly one request body. POST /chats/{chatId}/stream/ doesn't accept a key; see stream errors for how to recover a turn.

Stream errors

POST /chats/{chatId}/stream/ fails in two ways. Before the event stream starts, it returns an ordinary JSON error. After it starts, a failure arrives as an error event with errorCode, message, and an optional retryAfterSeconds, and the stream ends after that event:

event: error
data: {"type":"error","errorCode":"error.rate_limited","message":"The service is busy right now. Please retry in a few moments.","retryAfterSeconds":7}

Handle an error event separately from assistant content; your stream parser should route it like any other control event in the event reference.

Do not automatically resend a turn after an error event or a dropped connection. The first attempt may already have produced work. Check GET /chats/{chatId}/messages/ and let the patient choose to retry. The end of the HTTP connection marks transport completion only; see end states.

Timeouts and uncertain outcomes

Set finite connection and total timeouts on ordinary JSON requests. A stream stays open for the whole assistant turn, so give it a longer read timeout and an explicit cancel action. The contract doesn't define one timeout value per workflow; choose limits that fit your patient experience.

A client timeout leaves the outcome unknown:

• For an idempotent mutation, retry with the same key and body.
• For any other mutation, read the resource to see whether the change happened before you replay it.
• For a stream turn, read the transcript before offering to resend the patient's message.

Request IDs

Responses carry an X-Request-ID header. Store it with your local request record, including for failures, so Doctronic can trace the request without you sending credentials or patient content. See report an API problem for what to include in a report. The SDKs expose it as requestId (TypeScript) and request_id (Python) on errors, streams, and raw responses.

Retry checklist

• Retry only failures the operation documents as temporary: network errors, 503, other 5xx on reads, and stream errors with retryAfterSeconds.
• Keep the same idempotency key and body when retrying a supported mutation.
• Read the resource before replaying a mutation without an idempotency key.
• Cap attempts and total elapsed time.
• Use exponential backoff with jitter, and wait at least Retry-After or retryAfterSeconds when present.
• Treat the end of a stream connection as transport completion, not consultation completion.
• Keep X-Request-ID with every failed request.

The SDKs apply this checklist for you. They retry reads and idempotent mutations after network errors, timeouts, 429, and 503, and idempotent mutations after an idempotency conflict, always with the same key and body. They back off exponentially with jitter, wait for Retry-After up to 60 seconds, stop after maxRetries / max_retries retries (default 2), and never retry a stream. Pass your own idempotencyKey / idempotency_key to keep a key across process restarts.