Documentation / Reference / Results and errors
Result and error taxonomy¶
VAANI separates a call's base outcome, detailed failure evidence, and post-Closure delivery status.
Call outcomes¶
CallOutcome |
Meaning |
|---|---|
COMPLETED |
graceful base outcome |
FAILED |
terminal runtime/provider/transport failure |
CANCELLED |
lifecycle owner cancellation |
TRANSFERRED |
admitted blind transfer ended the conversation |
The optional Judge annotates evidence and cannot change this base outcome.
Error categories¶
ErrorCategory groups stable codes into invalid input/state, unsupported,
authentication/permission/not-found, rate/quota, deadline/unavailable,
content/protocol, transport, and internal failures.
Representative ErrorCode boundaries:
| Area | Codes |
|---|---|
| Setup/state | SETUP_INVALID, CALL_STATE_INVALID |
| Updates | UPDATE_STALE_REVISION, UPDATE_SUPERSEDED, UPDATE_UNSUPPORTED, FALLBACK_NOT_EQUIVALENT |
| Credentials/access | CREDENTIAL_UNAVAILABLE, CREDENTIAL_REJECTED, PROVIDER_ACCESS_DENIED |
| Capacity | PROVIDER_RATE_LIMITED, PROVIDER_QUOTA_EXHAUSTED, PROVIDER_UNAVAILABLE |
| Deadlines | PROVIDER_ATTEMPT_TIMED_OUT, OPERATION_TIMED_OUT, PARTICIPANT_READINESS_TIMED_OUT |
| Tools | TOOL_ARGUMENT_INVALID, TOOL_RESULT_INVALID, TOOL_EXECUTION_FAILED, TOOL_COMPLETION_UNKNOWN |
| Transport/recording | CONNECTION_FAILED, PRIMARY_PARTICIPANT_DISCONNECTED, RECORDING_UNAVAILABLE |
| Integrity | PROVIDER_OUTPUT_INVALID, INTERNAL_INVARIANT_BROKEN |
This table is intentionally representative. The exact current enums and
serialization contract are in src/vaani/_model.py and
contracts/public/v1/schemas/voice-runtime-error.schema.json in the source
repository.
Typed control-flow errors¶
| Type | Boundary |
|---|---|
InvalidCallSetup |
preflight failed before lifecycle ownership; no result |
CallStartFailed |
startup/controller failure |
UnsupportedUpdate |
adapter cannot perform requested change; old revision stays active |
InvalidCallState |
operation is inadmissible in current state |
Inspect retry.may_retry, remediation codes, and selected action. Do not retry
solely because a provider exception looked transient.
Result failures¶
FailureRecord names one primary error ID, zero or more secondary IDs, and
ordered FailureEntry records. Cleanup failure can be secondary without erasing
the primary cause.
Delivery dispositions¶
Post-Closure publishers return SUCCEEDED, FAILED, TIMED_OUT, CANCELLED,
or CONFLICT. These describe sink delivery only and never mutate the call
outcome.
Next: results concept or troubleshooting.