Errors and retry behavior | HIS User documentation

ICAP returns HTTP status codes. Error responses use a Problem Details-style object with fields such as type, title, status, and detail. Treat detail as explanatory text, not as a stable programmatic code.

Status	Meaning	Recommended action
`400 Bad Request`	The request is malformed or fails validation.	Correct the request; do not retry unchanged.
`401 Unauthorized`	Authentication failed.	Obtain a valid HID Authentication Service token.
`403 Forbidden`	The caller is authenticated but lacks permission.	Correct the tenant, role assignment, or role permissions.
`404 Not Found`	The tenant or active resource was not found.	Verify IDs and lifecycle state; do not create a replacement automatically.
`409 Conflict`	A business rule or concurrent write prevented completion.	Re-read the relevant state and resolve deliberately.
`412 Precondition Failed`	`If-Match` did not match the current version.	Re-read and reconcile.
`428 Precondition Required`	A guarded operation lacks a valid `If-Match`.	Supply the current numeric version.
`500 Internal Server Error`	ICAP encountered an unexpected failure.	Record the request context and contact support if it persists.
`503 Service Unavailable`	ICAP or a dependency is temporarily unavailable.	Retry with bounded exponential backoff and observability.

Retry safely

Retry only requests whose result you can safely determine. A network timeout does not prove that ICAP did not complete the request.

For read operations, It is safe to retry on network timeouts or 503 Service Unavailable using bounded exponential backoff.
For create operations, a network timeout does not mean creation failed. Store a stable external identifier, query the target resource first upon failure, and create only if no matching record is found.
For guarded updates, re-read after 409 or 412; never retry a stale update unchanged.
For delete and purge, inspect the current lifecycle state. Purge is not an idempotent second success.
For PACS-backed behavior, distinguish successful ICAP acceptance from downstream completion and inspect PACS transactions.

Log the tenant, resource ID, operation, response status, and a safe correlation ID. Never log bearer tokens, PIN values, or unnecessary personal data.