Errors, idempotency, and retries
Handle HTTP failures, stream errors, idempotent mutations, and uncertain outcomes.
JSON errors contain a stable machine-readable code and a human-readable message. Some errors
also include data.
{
"code": "error.auth.unauthorized",
"message": "Unauthorized."
}HTTP status guidance
| Status | Meaning | Handling |
|---|---|---|
400 | The request is invalid for the current workflow | Correct the request. Do not retry it unchanged. |
401 | API authentication failed | Stop using the credential and coordinate replacement or rotation with Doctronic. |
403 | The organization cannot act on the selected user | Stop and verify the patient-to-user mapping. |
404 | The resource is absent from the authenticated scope | Treat it as unavailable without revealing whether it exists elsewhere. |
409 | State or idempotency conflict | Inspect the endpoint error code before deciding whether to refresh or retry. |
422 | The request shape failed validation | Correct field types and constraints. |
503 | The operation cannot start safely or the service is temporarily unavailable | Retry only according to the endpoint contract. |
Other 5xx | Service failure | Retry safe reads with bounded exponential backoff and jitter. |
Individual endpoints can define more specific behavior. Artifact retrieval returns 202 while a
document is processing and uses 500 for a permanent generation failure. Use the endpoint
reference as the source of truth.
Idempotent mutations
These operations accept an Idempotency-Key header:
POST /users/POST /chats/POST /appointments/scheduled/POST /appointments/asap/POST /appointments/{appointment_id}/cancel/POST /appointments/{appointment_id}/reschedule/PUT /address/POST /pharmacy/search/PUT /pharmacy/
Generate a unique, opaque key for one intended operation. If the response is lost, retry the exact same method, path, and body with the same key. The stored result is available for 24 hours and a replayed response includes:
Idempotency-Replayed: trueDo not reuse a key for a different request. A key used with a different payload, or a first request
that is still being processed, returns 409. If the API cannot coordinate idempotency safely, it
returns 503 and does not start the mutation.
The chat streaming operation does not accept an idempotency key. After an interrupted stream,
inspect GET /chats/{chatId}/messages/ before allowing an explicit user retry.
Stream errors
Before SSE begins, the stream endpoint can return an ordinary JSON error response. After SSE has
started, a recoverable failure can arrive as an error event. Its documented fields are
errorCode, message, and optional retryAfterSeconds.
Handle a stream error separately from assistant content. If retryAfterSeconds is present, wait
at least that long. Do not automatically resend a turn after partial output because the first
attempt may already have created work.
Retry checklist
- Retry reads only for failures the endpoint identifies as temporary.
- Preserve the same idempotency key and body when retrying a supported mutation.
- Reconcile the resource before replaying a mutation that does not accept an idempotency key.
- Set a maximum number of attempts and elapsed time.
- Add exponential backoff and jitter.
- Treat the end of an SSE connection as transport completion, not consultation completion.
- Retain
X-Request-IDwith local request metadata for investigation.