Handle API Request Tool responses and errors

An API Request Tool should return enough structured information for the assistant to distinguish a completed action from a rejected or failed request. Use HTTP status codes for success and failure, return JSON consistently, and give each error a stable code and actionable message.

Design the response contract

Return a 2xx status only when the requested action succeeds. The coffee-order quickstart endpoint returns 201 Created with the server-calculated total and a mock order number:

1
{
2
  "success": true,
3
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
4
  "orderId": 47730,
5
  "productName": "House coffee beans",
6
  "quantity": 2,
7
  "totalCents": 3600,
8
  "totalDisplay": "$36.00",
9
  "message": "Your mock order for 2 House coffee beans was accepted for $36.00."
10
}

Return a non-2xx status when the action does not complete. Keep the error body machine-readable and consistent:

1
{
2
  "success": false,
3
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
4
  "error": {
5
    "code": "VALIDATION_ERROR",
6
    "message": "Request body failed validation.",
7
    "details": [
8
      {
9
        "field": "productId",
10
        "code": "INVALID_ENUM_VALUE",
11
        "message": "productId must be one of: coffee-beans, tea-sampler, ceramic-mug."
12
      }
13
    ]
14
  }
15
}

The API Request Tool treats a non-2xx response as a failed request. If a backoff plan is configured, the status code also determines whether the request is eligible for a retry. See Handle latency and retries before enabling retries.

Test successful and failed responses

Test the destination API directly before involving an assistant. This separates endpoint behavior from tool selection, schema, prompting, and voice-call behavior.

$
curl --request POST \
>
  --url https://vapi-docs-orders.val.run/ \
>
  --header "Content-Type: application/json" \
>
  --include \
>
  --data '{
>
    "customerName": "Alex",
>
    "productId": "coffee-beans",
>
    "quantity": 2
>
  }'

Decide how the assistant should recover

Add explicit failure behavior to the assistant’s system prompt. The assistant must not claim that an order succeeded unless the tool returned a successful response.

When createCoffeeOrder fails, do not say that the order was accepted and do not invent an order number or total.
If the error identifies an invalid field, explain the allowed value in plain language, collect the corrected value, read the complete order back, and get confirmation before calling createCoffeeOrder again.
For a timeout, connection failure, or server error, apologize and explain that the order was not confirmed. Offer to try again, but call createCoffeeOrder again only after the caller agrees.

Use a system-role request-failed message when the model should adapt its response to the returned error and conversation context. Use an assistant-role message only when the same fixed sentence is appropriate for every failure. See Keep the caller informed for message configuration.

Inspect a call

After a test call, inspect the tool arguments and result before changing the schema or prompt.

The call artifact does not show the final HTTP request after Vapi resolves Liquid values and merges static fields. Use logs from the destination API to inspect final headers and body values. Correlate the coffee endpoint’s requestId with its X-Request-Id response header and server logs when investigating a specific request.

Diagnose common failures

For broader issues with tool selection, schemas, and model-visible responses, see Custom tools troubleshooting. For call-level failures, see Troubleshoot call errors.