session_already_completed (409)

← Error reference

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

Five routes return it when the session's `status` is outside the set that route accepts. 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}/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 only for a `payment_required` session, and 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, the passed deadline, or for a `payment_required` session the 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 terminal status, create a new session for the applicant if you need to verify them again.

Payment required: how a paused verification resumes, and the one that does not

Example response

{
  "error": {
    "type": "https://docs.checktiv.com/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.checktiv.com/api/errors/session_already_completed",
    "details": {
      "status": "completed"
    }
  }
}