session_already_completed (409)
session_already_completed
HTTP status: 409
Retryable: No. Retrying without changes will fail the same way.
The session's current status does not allow this operation.
When it fires
Six routes return it when the session's status is outside the set that route accepts, or the session can no longer be finished. Not every refused status is terminal. POST /v1/sessions/{id}/manual_review and POST /v1/sessions/{id}/reset_and_resend accept only created, pending and in_progress. So they also refuse the in-flight statuses awaiting_gate, awaiting_recapture and processing, and a payment_required session, which is paused on funds. POST /v1/sessions/{id}/reset_and_resend also refuses a session that can no longer be finished: one past its deadline, or past the window in which a new link can still reach it. POST /v1/sessions/{id}/reset_and_resend also returns it for a session that belongs to a reservation from a connected system whose due time has passed, and then resets and sends nothing. It asks about the reservation after its own status and deadline checks, so a session those checks refuse keeps that refusal. POST /v1/sessions/{id}/cancel accepts those three statuses and payment_required, so it refuses only the in-flight and terminal statuses. POST /v1/sessions/{id}/browser_token refuses a session that is terminal or past its deadline. POST /v1/sessions/{id}/resend returns it for a payment_required session, for a session that can no longer be finished, and for a session that belongs to a reservation from a connected system whose due time has passed. It asks about the reservation after its own status checks, so it answers a finished, expired or canceled session with session_finished. POST /v1/sessions/{id}/regenerate_link returns it for a payment_required session, for a session that can no longer be finished, and for a session that belongs to a reservation from a connected system and can no longer be finished, such as one past the reservation's due time, or one that expired or was canceled. It asks about the reservation first, so a paused session of such a reservation gets the reservation's next step from it and the funds next step from resend and reset_and_resend. It answers a finished session with session_finished. The terminal statuses are completed, awaiting_review, expired and cancelled, and a terminal session cannot be changed. details.status carries the session's status, and the message names the cause: the terminal status, a session that can no longer be finished (with the next step), for a payment_required session the next step, or for a reservation's session that can no longer be finished the reservation's next step.
How to handle it
Read details.status first. A payment_required session is waiting on funds. It is paused until the account balance can pay for its next check: add funds in Billing, or follow the steps there for a frozen or locked wallet, and it resumes automatically. A session that stopped at its document-signing step before the document was prepared does not resume; create a new session for the applicant instead. Do not create a second session while this one can still resume: both would run, and the account would pay twice for one applicant. To abandon a paused session, cancel it with POST /v1/sessions/{id}/cancel. For awaiting_gate, awaiting_recapture or processing, the verification is still in progress: wait for it to finish, then read its outcome from GET /v1/sessions/{id} or the webhook. For a session that can no longer be finished, the applicant cannot complete it, and nothing you do to this session changes that. Create a new session for the applicant. For a terminal status, create a new session for the applicant if you need to verify them again. A session that belongs to a reservation from a connected system and was not finished is the exception. Open the applicant's detail page in the console before you create a new session: it shows the reservation's next step, such as reopening it. A session you create is not part of the reservation, so the connected system does not receive its result. A continue_blocked_reason of deadline_passed marks such a session once the reservation's due time has passed.
Payment required: how a paused verification resumes, and the one that does not
Example response
{
"error": {
"type": "https://docs-dev.autohost-dev.uk/api/errors/session_already_completed",
"code": "session_already_completed",
"message": "Session is in terminal state 'completed' and cannot be cancelled",
"request_id": "req_01HEXAMPLE0000000000000000",
"doc_url": "https://docs-dev.autohost-dev.uk/api/errors/session_already_completed",
"details": {
"status": "completed"
}
}
}