Errors

Error format

Except for 401, which returns an empty body, every error follows the same structure:

type SoftIntegrationError = {
  message: string;
  errorType: string;
};

Generate signature

Endpoint: POST /api/v1/generate-soft-integration-signature

Status	`errorType`	Cause	What to do
`400`	`missingOrInvalidParameter`	`organizationId`, `email` or `requestId` missing or malformed.	Fix the payload.
`400`	`duplicatedRequestId`	The `requestId` was already used, whether the session is live, finished or cancelled.	Generate a new `requestId`. They are never reusable.
`400`	`invalidApiVersionForEndpoint`	The `X-Invox-Medical-Api-Version` header targets a version that does not implement this endpoint.	Send `2026-08-01` or omit the header.
`401`	—	The access token is missing, malformed or expired.	Request a new access token.
`403`	`invalidPermission`	The API Key does not hold `GENESIS-SOFT-INTEGRATION`.	Enable the permission for that API Key.
`403`	`userNotEligible`	Unknown, disabled, or out-of-organization physician.	Check the user exists, is enabled and belongs to the organization.
`409`	`activeSessionExists`	Two signature requests for the same physician raced each other.	Retry. A previous session no longer causes this: it is cancelled automatically.

Get consultation result

Endpoint: GET /api/v1/soft-integration/{requestId}/result

Status	`errorType`	Cause	What to do
`400`	`invalidApiVersionForEndpoint`	The `X-Invox-Medical-Api-Version` header targets a version that does not implement this endpoint.	Send `2026-08-01` or omit the header.
`401`	—	No valid credential supplied.	Request a new access token.
`403`	`invalidPermission`	The `requestId` belongs to another organization.	Check you are using the credentials of the right tenant.
`404`	`requestNotFound`	No consultation exists for that `requestId`.	Check the identifier.
`409`	`resultNotReady`	The consultation has not finished yet.	Wait for the notification instead of polling.
`410`	`resultExpired`	The result was removed from temporary storage.	Not recoverable. The consultation must be repeated.

Cancel consultation

Endpoint: DELETE /api/v1/soft-integration/{requestId}

Status	`errorType`	Cause	What to do
`400`	`invalidApiVersionForEndpoint`	The `X-Invox-Medical-Api-Version` header targets a version that does not implement this endpoint.	Send `2026-08-01` or omit the header.
`401`	—	No valid credential supplied.	Request a new access token.
`403`	`invalidPermission`	The API Key does not hold `GENESIS-SOFT-INTEGRATION`, or the `requestId` belongs to another organization.	Check the permission and the tenant credentials.
`404`	`requestNotFound`	No consultation exists for that `requestId`.	Check the identifier used when generating the signature.
`409`	`sessionAlreadyFinished`	The consultation already finished or was cancelled.	Nothing to do: the physician is already free.

Opening Invox Genesis

Opening the consultation view is a browser navigation, not an API call, so there is no error payload: the physician is redirected to a neutral access error page and no session is established.

Situation	Cause
Unknown or expired signature	More than 3 hours elapsed since it was issued, or it was never issued.
Already exchanged signature	The URL was reused.
Cancelled consultation	The session was released with Cancel consultation.

WebSocket

Situation	Behaviour
Invalid signature	The handshake is rejected with `401` and the connection is not established.
Expired signature	The handshake is rejected with `401`.
Malformed message	An `{ "type": "error", "error": "INVALID_JSON" }` message is returned; the connection stays open.
Unsupported `action`	An `{ "type": "error", "error": "UNKNOWN_ACTION" }` message is returned; the connection stays open.
Inactivity	The connection is closed after roughly 10 minutes without traffic. Send `ping` messages.

A physician can only have one active SOFT Integration session at a time. Requesting a new signature for a physician who already has one cancels the previous session automatically: the latest one always wins. The displaced consultation stops working and produces no result.

Request one signature per consultation, at the moment the physician opens it.

Need a different behaviour for a specific deployment? Contact support with your organization identifier and your expected volume.

NotificationsWebhook

Help & support