When it waits for a human

A licensed clinician releases every submission before it reaches a payer. Your integration has to accommodate that, and the ways of getting it wrong are predictable.

#What you will see

json

"status": { "state": "input-required" }

It means: the task is proceeding correctly, and it is blocked on something outside the machine loop. You cannot satisfy it. There is deliberately no method that releases a gate - a release requires a named licensed human authenticated at the practice.

#What to do

Surface it
Tell whoever is waiting that it is with the practice for clinical review, and name the practice. A user watching a spinner with no explanation will call somebody.
Poll slowly
Every two to five minutes is plenty. A clinician is reading a chart, not pressing a button on a timer.
Set an expectation, not a timeout
Do not fail the task at ten minutes. Practices work in sessions; a request sent at 4pm may be released the next morning, and that is normal.
Keep the task id
It is the only handle. Losing it means you cannot find out what happened without asking us.

#Four ways to get this wrong

Mistake	What actually happens
Treating `input-required` as a failure	Your retry creates a duplicate task. A clinician now has two identical requests to review and no way to tell which one you are tracking.
Polling every second	You hit the rate limit, we throttle you, and the answer arrives later than it would have.
Timing out after a few minutes	You report a failure for a request that is going to succeed, and your user gives up on something that was working.
Resending on any non-`completed` state	The worst version of the first mistake. Every poll becomes a new task.

Duplicates are a real clinical problem

Two authorizations for one procedure can produce two approvals, two claims, and a reconciliation problem for the practice. We de-duplicate what we can see, but a task you created twice with different ids looks like two intentional requests.

#If you need to cancel

json

{"jsonrpc":"2.0","id":"9","method":"tasks/cancel","params":{"id":"task-8f21c"}}

Works before transmission. After a submission has reached the payer, cancelling is a void - which is itself a clinical action requiring a human, so it becomes a new task rather than an immediate result.