When a consult fails
One fact governs every decision on this page:
A consult cannot be re-recorded. The animal has left the room.
So the question is never "how do I retry this". It is "what can the vet still salvage". Getting this wrong is the difference between a vet writing the record from a transcript in two minutes and a vet losing the consultation.
Never ask a vet to re-record a consult that is over.
Most failures still leave you a transcript
The transcript is stored as soon as transcription succeeds, and that happens before the note is written. So when note generation is what failed, the transcript is already on the note and comes back with it.
That is the single most valuable thing in this API when something goes wrong. Show it. A vet with the transcript in front of them can write the record themselves; a vet shown only an error message has lost the consultation.
Check for a transcript before you tell anyone the consult is gone, including on a failed note. The Note object says exactly when the field is present.
Reading a failure
Three questions decide what your product should do. The errors page gives the current answer for each code, and it is generated from the API specification, so it is the copy that stays right.
- Is there a transcript? If there is, the vet can still write the record, and that is the outcome to aim for. Check the note for one before you branch on anything else.
- Is the failure ours or yours? Some are on our side and have already been retried internally before they ever reach you. A retry loop in your product adds delay to a consult that is already over and changes nothing.
- Is there anything the vet can act on? Sometimes it is a hardware check before the next consult. Sometimes it is nothing at all, and saying so plainly beats an error message that implies a retry that will not work.
A failed note with no error code at all is possible, and means the consult was lost somewhere we could not name. Treat it as unrecoverable and show the vet whatever you have.
Do not copy the per-code remedies into your own documentation or your own code comments. We add codes within /v1, and a copy is how the advice goes stale.
Failures before the consult started
Some refusals arrive at submit time, before any work is done. Two are worth designing around rather than just reporting:
An inactive subscription. Discovering this at submit time means the consult is already over and the audio already captured, which is a failure the vet cannot do anything about. Read getConnection when your consultation screen loads and hide or disable recording when the practice cannot generate notes. The value changes rarely enough to cache for the session.
A revoked connection. The vet disconnected or left the practice. Handle it by clearing the stored token and offering to reconnect, not by retrying.
A note that generated but may be incomplete
A note can come back successfully and still deserve a warning. If less audio reached us than your recorder reported capturing, part of the consult was lost in transit.
We build the note anyway, because a retry cannot recover audio that was never delivered, but the vet needs to know the record may be incomplete before they file it. Show that warning. It is the one case where a technically successful response should still put something in front of the vet.
This check only runs when you send captured_seconds on submission. Omit it and we have no way to tell a short consult from a truncated one. See NoteWarning.
Retrying safely
Retrying a submission is safe as long as you reuse the same idempotency key, which returns the original note rather than generating and charging for a second one. That is covered in how an integration fits together.
A 502 means nothing was consumed and no note was created, so retry it shortly. A rate limit means back off and respect Retry-After. Everything else in the 4xx range should not be retried unchanged.