How to read VICIdial API SUCCESS and ERROR responses

You called a VICIdial function and got back a line of text. No JSON envelope, no status code to lean on — just words. Once you know the shape, that line tells you everything: whether the call worked, what it did, and why it did not. The format is the same across the API, so a few minutes spent learning it pays off on every function you ever call.

Three words to watch for

Most Non-agent API replies open with one of three words. SUCCESS means the action ran. ERROR means it did not, and the rest of the line says why. NOTICE sits in between — used by bulk operations to report what happened to each item, item by item.

SUCCESS: hopper_bulk_insert LEADS HAVE BEEN INSERTED INTO THE HOPPER - 2|0|8432948|6666
ERROR: campaigns_list USER DOES NOT HAVE PERMISSION TO GET CAMPAIGN INFO - 6666|0
NOTICE: hopper_bulk_insert NOT ADDED TO HOPPER, LEAD NOT FOUND - 193715

After the first word comes the function name, then a short message, then a dash and some pipe-separated values that fill in the specifics — a user, a Lead id, a count. That layout is consistent enough that you can split on the dash and then the pipe to pull out the parts you care about.

NOTICE lines matter most on bulk calls. When you insert many leads at once, you may get one NOTICE per lead — added, not found, already present, outside local call time — followed by a final SUCCESS or ERROR summary line. Read every NOTICE, not just the last line, or you will miss the leads that quietly failed.

When success has no label

Here is the part that trips people up. Functions that return data — listing campaigns, reading the Hopper, listing audio files — do not print the word SUCCESS at all. They just print the rows. The data is the success signal. A campaigns_list call returns pipe-delimited fields like this:

TESTCAMP|Test Campaign|Y|---ALL---|INBOUND_MAN|1|DOWN|PDROP DROP B NEW|65|9|9|9

A parsing routine that holds up

flowchart TD
    A[Read response line] --> B{Starts with ERROR?}
    B -->|Yes| C[Fail and log the message]
    B -->|No| D{Starts with SUCCESS or NOTICE?}
    D -->|Yes| E[Split on the dash for details]
    D -->|No| F[Treat the line as returned data]
    E --> G[Split values on the pipe]
    F --> G

Check for ERROR first and bail. Then, for the rest, split the line on the dash to separate the message from the pipe-separated values, and split those values on the pipe. That one routine reads almost every API (application programming interface) response you will meet. Newer VICIdial builds can also emit JSON output for some functions, which removes the guesswork if your tooling prefers it.

Setting a clear source on each call makes a confusing reply far easier to trace back to its caller — see what the API source parameter is for. For where response handling fits in the whole stack, read the VICIdial API and AGI overview.

Managed VICIfast servers ship a current VICIdial build, so the JSON output option is there when you want it. See what is included on the pricing page.