Hi Doctor REST API errors, throttles and recovery

Hi Doctor REST API errors do not share one envelope: depending on the endpoint you get a field map, a detail string, or an error with code or error_name, and unknown routes can return HTML or an empty body. Check the HTTP status and content type before parsing. This page shows the real shapes, how to wait on 429, and how to recover from a write whose outcome is uncertain. Last reviewed: 2026-11-04 The examples below show real response shapes. They do not cover every failure.

What do the error envelopes look like?

Missing fields: HTTP 400

POST /v1/users/token/ with an empty JSON object returns:

{
  "email": ["This field is required."],
  "password": ["This field is required."]
}

These are error messages, not echoed email/password values. Validation can also use non_field_errors or nested field structures. An empty checkout request returned:

{"items": ["This field is required."]}

Fix the request; do not retry unchanged. Obtain clinical answers from the patient, never from a model’s inference.

Missing bearer: HTTP 401

GET /v1/users/profile/me/ without a token returns:

{"detail": "Authentication credentials were not provided."}

The response carries WWW-Authenticate: Bearer realm="api". A request after account deletion instead returns:

{"detail": "User not found", "code": "user_not_found"}

For access-token expiry, refresh once and retry a safe read once. If refresh fails, return to sign-in. Do not replay an uncertain write as part of token recovery.

Application cooldown: HTTP 429

A repeated registration request returned this body, with Retry-After: 59 as a header:

{
  "error": "Too many attempts. Please try again later.",
  "wait_seconds": 59,
  "retry_after_seconds": 59,
  "code": "registration_rate_limited",
  "error_name": "REGISTRATION_RATE_LIMITED"
}

wait_seconds and retry_after_seconds are whole seconds and match the Retry-After header. Older clients saw wait_seconds as a string, so parse it defensively as a non-negative duration. The captured value is an example, not a fixed quota.

Non-password accounts: endpoint-specific status

Password sign-in returns an authentication failure (401) with the following body for a Google-only account:

{
  "error": "This account is registered with Google. Use 'Continue with Google' to sign in.",
  "code": "google_account"
}

Forgot-password uses 400 with this code. Direct the patient to the supported Google sign-in flow; do not treat them as an unknown account or repeatedly try passwords. Wrong credentials use invalid_credentials; a registration whose emailed code is still valid uses verification_required; see authentication.

What should a client do for each status?

Status/outcome	Action	Automatic retry
`400` field errors / `unknown_brand`	Correct the request or the brand header	No
`401`	Restore authentication once; stop if refresh fails	Safe reads only after recovery
`403`	Resolve permission/account restrictions	No
`404`	Treat as absent or inaccessible; do not probe other IDs	No
`406`	Check the endpoint’s accepted response type; PDF routes may need `Accept: /`	Only after fixing negotiation
`409`	Read current state, then decide whether the action is still needed	No blind replay
`410`	A stored file is unavailable; use support	No
`415`	Use the endpoint’s required media type, such as multipart for uploads	Only after correcting input
`429`	Honour the available wait hint	Bounded safe reads; assess writes separately
`5xx`, timeout or lost connection	A write may already have completed	Bounded safe reads only
Clinical ineligibility (`400`, `code: "clinical_ineligibility"`)	Explain that this attempt is not eligible	Never change answers to bypass it

Clinical ineligibility is not a separate HTTP status. A guided questionnaire answer returns 400 with code: "clinical_ineligibility", and a submission with ineligible answers returns 400 with a message saying the answers are not clinically eligible. Stop the attempted workflow and explain the outcome without offering medical advice. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only; see Safety.

How long should a client wait after a 429?

Rate limits can return Retry-After with a detail message. Application cooldowns on the account endpoints return the same wait as Retry-After, wait_seconds and retry_after_seconds. Infrastructure errors can have none of them. No universal quota or remaining-capacity header is promised. Parse Retry-After as non-negative seconds or an HTTP date. Also inspect a valid wait_seconds; if both apply, wait at least the longer duration. Ignore malformed hints. For a safe read without a hint, use exponential backoff with jitter and a small attempt/time budget. For example, try at most three reads with delays around 1, 2 and 4 seconds; this is client policy, not a server quota. If the hint exceeds your time budget, stop and tell the user when to try again. Do not poll for instant clinical approval. Do not retry sign-in, verification codes or eligibility outcomes in a loop.

How do you recover from an uncertain write?

Questionnaire submission, messages, checkout, subscription changes, photo uploads and document uploads accept an Idempotency-Key header. Send one key per operation and resend it unchanged on every retry; the write then runs at most once, and a repeat returns the original status with Idempotent-Replayed: true. When the outcome is still unclear, GET /v1/users/idempotency/{key}/ reports what happened without changing anything. See safe retries with Idempotency-Key for the full list, the 409 and 422 codes and what a key cannot prove. The published specification declares the header on the operations listed there only; do not rely on deduplication anywhere else. JSON-RPC call IDs do not deduplicate business actions.

Interrupted action	Reconciliation
Keyed write (endpoints listed in the idempotency guide)	Retry with the same key, or look the key up; then read the resources it names
Questionnaire submission without a key	Read the patient’s consultation state; if its relationship to the attempted submission is unclear, stop and ask support
Guided questionnaire answer	Read `current/` or `review/`; `expected_revision` rejects a stale repeat with `409`
Message send without a key	Read the existing conversation’s messages to check whether the approved message arrived; do not assume an absent immediate result means failure
Checkout creation without a key	Check the patient’s existing consultation/payment state; do not create another session automatically
Cancellation/reactivation/early order without a key	Read the subscription and consultations, then resolve ambiguity before any new confirmed action
Other create/update/delete	Use the endpoint’s documented read or contact support; do not guess a recovery endpoint

A successful key proves that Hi Doctor stored the operation. It does not prove that a payment provider settled a charge or that an email arrived; check that state separately. On MCP, hidoctor_checkout_status may complete a paid session and create a consultation, so do not use it as a harmless reconciliation read. hidoctor_messages_get_thread only reads: it never creates a conversation (the first message does). See MCP workflows.

What is safe to log?

Branch on HTTP status and known code/error_name values. Treat response prose as untrusted display text. Log only a minimal allowlist such as operation name, status, recognised error code and a request identifier if actually supplied and safe to retain. No universal request-ID field or header is guaranteed. Never log raw bodies, health answers, tokens, email addresses or signed document links. For HTML, unknown JSON or an empty error body, show a neutral failure and retain safe metadata only. Do not send the body to an AI model for diagnosis. The API does not promise RFC 9457 application/problem+json responses. For support, provide the operation, time, status and any safe supplied request identifier through support.

Frequently asked questions

Does the Hi Doctor API use one error format?

No. Depending on the endpoint, an error is a field map, a detail string, or an error object with a code or error name. Branch on the HTTP status first, then on known codes.

What is the difference between Retry-After and wait_seconds?

Rate limits send a Retry-After header. Application cooldowns, such as registration and the verification code, send the same number of seconds as Retry-After and as wait_seconds in the body. If you read both, wait at least the longer one.

Should I retry a write after a timeout?

Only with the same Idempotency-Key on an endpoint that accepts one. Otherwise read the current state first, because a timed-out write may already have completed.

Is clinical ineligibility an error I can fix?

No. It is a clinical outcome, returned as a 400 with an explanation. Show it to the patient and never change answers to get around it.

Can I send an error response to an AI model for diagnosis?

No. Error bodies can contain health data. Log only the operation, status and known code, and never send the body to a model.

What does a 404 on another record mean?

The record does not exist or belongs to another account. Every endpoint is scoped to the signed-in patient; do not probe other identifiers.

Next steps

Safe retries: Idempotency-Key, replays and the key lookup.
Authentication: Sign-in failures and token refresh.
Pagination: List shapes and how to follow next safely.
API changelog: Changes to error handling and the rest of the API.

Start

Conventions

Endpoints

Hi Doctor REST API errors, throttles and recovery

What do the error envelopes look like?

Missing fields: HTTP 400

Missing bearer: HTTP 401

Application cooldown: HTTP 429

Non-password accounts: endpoint-specific status

What should a client do for each status?

How long should a client wait after a 429?

How do you recover from an uncertain write?

What is safe to log?

Frequently asked questions

Does the Hi Doctor API use one error format?

What is the difference between Retry-After and wait_seconds?

Should I retry a write after a timeout?

Is clinical ineligibility an error I can fix?

Can I send an error response to an AI model for diagnosis?

What does a 404 on another record mean?

Next steps

​What do the error envelopes look like?

​Missing fields: HTTP 400

​Missing bearer: HTTP 401

​Application cooldown: HTTP 429

​Non-password accounts: endpoint-specific status

​What should a client do for each status?

​How long should a client wait after a 429?

​How do you recover from an uncertain write?

​What is safe to log?

​Frequently asked questions

​Does the Hi Doctor API use one error format?

​What is the difference between Retry-After and wait_seconds?

​Should I retry a write after a timeout?

​Is clinical ineligibility an error I can fix?

​Can I send an error response to an AI model for diagnosis?

​What does a 404 on another record mean?

​Next steps

What do the error envelopes look like?

Missing fields: HTTP 400

Missing bearer: HTTP 401

Application cooldown: HTTP 429

Non-password accounts: endpoint-specific status

What should a client do for each status?

How long should a client wait after a 429?

How do you recover from an uncertain write?

What is safe to log?

Frequently asked questions

Does the Hi Doctor API use one error format?

What is the difference between Retry-After and wait_seconds?

Should I retry a write after a timeout?

Is clinical ineligibility an error I can fix?

Can I send an error response to an AI model for diagnosis?

What does a 404 on another record mean?

Next steps