VICIdial API automation that does not hide failures

Design your own operation key — neither API gives you one

Fast answer: neither the Agent API nor the Non-Agent API accepts an idempotency key from you — there is no field to send one in, so idempotent automation is a property your own client has to build, not a contract either endpoint offers. Give every intended mutation a stable key derived from the source event and the target identity, kept in your own ledger, and use it to decide whether an operation already happened before you send it again.

VICIdial already ships two purpose-built dry-run mechanisms instead of a generic idempotency key: the Non-Agent API's add_lead's duplicate_check field (DUPLIST, DUPCAMP, DUPSYS and several other scoped variants — see vicidial-non-agent-api-guide for the complete list) refuses to create a second lead for a number already present in the scope you choose, and its update_lead's no_update=Y flag reports whether a matching lead exists without writing anything — see safe-callback-migration for no_update used exactly this way on a real migration. Prefer one of these shipped checks over a bespoke scheme wherever the function you are calling actually offers one.

Both APIs enforce the same allow-list before either question above even matters: vicidial_users.api_allowed_functions is a space-delimited list of the exact function names one account may call, or the literal ALL_FUNCTIONS; the Agent API additionally requires vdc_agent_api_access set on that same row. A function absent from that list is rejected before your idempotency design is ever exercised, so confirm it once, for the account your automation will actually use, before writing a retry loop that will only ever receive the same rejection.

SELECT user, user_level, api_allowed_functions, vdc_agent_api_accessFROM vicidial_usersWHERE user = '<AGENT_USER>';

Classify transport, VICIdial output and NOTICE separately

An HTTP response says whether the web request completed; the VICIdial response body says whether the requested function accepted its parameters. A 200 response containing ERROR is an application rejection, not success.

The local example below is intentionally small. It never sends a request; it turns a sanitized status/body into a category so dependent work can stop on unknown outcomes.

A plain-text response is not always exactly SUCCESS or ERROR, either. AGENT_API.txt documents a third class, prefixed NOTICE, for a condition that is neither: external_dial's own worked example shows NOTICE: defined dial_ingroup not found when an optional field names something that does not exist, and the call still proceeds. Classify that separately from an outright rejection instead of letting it fall into the same bucket as a genuinely unrecognized response.

function classify(httpStatus, body) {  const text = String(body).trim();  if (httpStatus >= 500) return 'retryable-server';  if (httpStatus === 401 || httpStatus === 403) return 'rejected-auth';  if (httpStatus < 200 || httpStatus >= 300) return 'rejected-http';  if (/^ERROR/i.test(text)) return 'rejected-application';  if (/^NOTICE/i.test(text)) return 'accepted-with-notice';  if (!text) return 'unknown-empty';  return 'verify-required';} console.log(classify(200, 'NOTICE: defined dial_ingroup not found - FAKE_INGROUP'));

Bound and classify retries

Retry transport failures and clearly temporary server responses with backoff. Do not retry validation, authentication or ambiguous partial-success responses without a read check.

Separate secrets from operator logins and redact them from command history, logs and support bundles.

A retryable-server classification and a rejected-application classification call for opposite behavior, so keep them on separate code paths rather than funneling every non-success result through one generic retry wrapper. Retrying an ERROR body a second time costs latency and produces the identical rejection every time, since the request was understood and refused, not lost.

curl --fail-with-body --silent --show-error --connect-timeout 5 --max-time 20 --config /etc/vicidial-api/agent.cfg --data-urlencode "function=version"

Verify outside the writer

Read the resulting lead, callback or user state back through a read-only path — /etc/vicidial-api/readonly.cfg's own Non-Agent API account, or a direct read-only database query — never by trusting the writer call's own response a second time. Keeping /etc/vicidial-api/writer.cfg's write-capable account separate from readonly.cfg's read-only one is not just tidiness: it means a verification step can never accidentally repeat the write it is supposed to be checking.

Report completed, already-complete, rejected, retryable and unknown outcomes separately. Unknown is a real state and should stop dependent work.

This is the same discipline vicidial-agent-api-guide and vicidial-agent-api-vs-non-agent-api teach for a single call; automation just needs it enforced every time, in code, rather than remembered by whoever happens to be watching a terminal that day.

Stop on unknown and reconcile before retry

When a write-capable job is later developed, an unknown timeout or malformed response must pause dependent work. First perform an independent read using the stable operation key and target identity; retry only when that read proves the operation was not committed.

Rollback must be a documented supported inverse operation or restoration workflow scoped to the exact synthetic or authorized record. Never guess by issuing the same mutation repeatedly or deleting rows directly.

• Completed, already-complete, rejected, retryable and unknown totals reconcile to input.
• Every retry has a bounded attempt count and backoff schedule.
• Secrets and response payloads remain out of URLs, process lists, source and logs.