From f1791c1740197642b52cec619633173d6308f561 Mon Sep 17 00:00:00 2001 From: dev-seth-vapi Date: Wed, 15 Jul 2026 05:22:41 -0700 Subject: [PATCH] PRO-3522 Document actionable errors and request IDs --- fern/calls/call-ended-reason.mdx | 4 + fern/debugging.mdx | 2 +- fern/docs.yml | 13 +- fern/errors/diagnostic-codes.mdx | 183 ++++++++++++++++++++ fern/errors/index.mdx | 86 +++++++++ fern/errors/validation-errors.mdx | 85 +++++++++ fern/issue-reporting.mdx | 16 +- fern/support.mdx | 12 ++ fern/tools/custom-tools-troubleshooting.mdx | 4 + 9 files changed, 399 insertions(+), 6 deletions(-) create mode 100644 fern/errors/diagnostic-codes.mdx create mode 100644 fern/errors/index.mdx create mode 100644 fern/errors/validation-errors.mdx diff --git a/fern/calls/call-ended-reason.mdx b/fern/calls/call-ended-reason.mdx index 4349eb71e..a3d0cea44 100644 --- a/fern/calls/call-ended-reason.mdx +++ b/fern/calls/call-ended-reason.mdx @@ -10,6 +10,10 @@ Every call in Vapi ends with an `endedReason` code that tells you exactly why it For the full list of possible `endedReason` values, see the [API reference](/api-reference/calls/list#response.body.endedReason). + +An `endedReason` describes how a call finished. It is different from a dashboard diagnostic code or an HTTP API error. For those errors, see [Errors and troubleshooting](/errors). + + ## Quick diagnosis Start here if a call failed and you want to quickly understand what happened: diff --git a/fern/debugging.mdx b/fern/debugging.mdx index fbe4e134e..d59949fc9 100644 --- a/fern/debugging.mdx +++ b/fern/debugging.mdx @@ -206,7 +206,7 @@ For any tool in your `Tools` section: | **Long silences** | Model processing delay | Use faster models or reduce response length | -For a complete list of error codes and what they mean, see [Call end reasons](/calls/call-ended-reason). To diagnose a failed call by symptom (e.g., "call dropped mid-conversation" or "assistant went silent"), see [Troubleshoot call errors](/calls/troubleshoot-call-errors). +For a dashboard or API error, start with [Errors and troubleshooting](/errors). For a call's `endedReason`, see [Call ended reasons](/calls/call-ended-reason). To diagnose a failed call by symptom (e.g., "call dropped mid-conversation" or "assistant went silent"), see [Troubleshoot call errors](/calls/troubleshoot-call-errors). ## Getting help diff --git a/fern/docs.yml b/fern/docs.yml index 3a8641ad6..96643d634 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -724,6 +724,17 @@ navigation: path: support.mdx collapsed: true contents: + - section: Errors and troubleshooting + path: errors/index.mdx + icon: fa-light fa-triangle-exclamation + collapsed: true + contents: + - page: Diagnostic code reference + path: errors/diagnostic-codes.mdx + icon: fa-light fa-rectangle-code + - page: API validation errors + path: errors/validation-errors.mdx + icon: fa-light fa-brackets-curly - page: How to Report Issues path: issue-reporting.mdx icon: fa-light fa-bug @@ -1030,7 +1041,7 @@ redirects: - source: "/clients" destination: "/sdks" - source: "/error_message_guide" - destination: "/calls/call-ended-reason" + destination: "/errors" - source: "/privacy" destination: "/privacy-policy" - source: "/call_forwarding" diff --git a/fern/errors/diagnostic-codes.mdx b/fern/errors/diagnostic-codes.mdx new file mode 100644 index 000000000..07c865f37 --- /dev/null +++ b/fern/errors/diagnostic-codes.mdx @@ -0,0 +1,183 @@ +--- +title: Diagnostic code reference +subtitle: Find the meaning, next step, and retry guidance for stable Vapi diagnostic codes +slug: errors/diagnostic-codes +--- + +Vapi uses stable diagnostic codes so you can identify an error even when the displayed wording improves over time. Open **Technical details** in the dashboard, copy the code, then search this page. + + +Use your browser's find command to jump directly to a code. The message beside the failed action remains the best first step because it includes the context for that attempt. + + +## Retry guidance + +| Guidance | Meaning | +|---|---| +| **Retry now** | The same action is safe to try again. | +| **Retry only unfinished changes** | The runtime marks a retry as safe, but part of the action already succeeded. Retry only the part named in the recovery step. | +| **Correct, then retry** | Change the named input, configuration, or account state before retrying. | +| **Complete recovery first** | The runtime marks the error as retryable after correction. Follow the recovery step; it may continue the current attempt, refresh state, or use a different action instead of repeating the original action. | +| **Wait, then retry** | The failure is likely temporary. Wait briefly before another attempt. | +| **Reconnect, then retry** | Restore your network connection before retrying. | +| **Follow the next step first** | Do not repeat the same action yet. Check the saved state or complete the stated recovery step first. | + +If the next step does not solve the problem, [collect the request ID and report the issue](/errors#request-ids). + +## Authentication + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `AUTH_PASSWORD_RESET_REQUEST_FAILED` | **We couldn’t send the reset email.** Vapi couldn’t start password recovery right now. | Keep the email as entered and try again. If your organization uses SSO, return to sign in and choose SSO. | Retry now | + +## Dashboard + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `DASHBOARD_AUTHENTICATION_REQUIRED` | **Sign in to continue.** Your Vapi session is no longer valid. | Sign in again, then try the action once more. | Correct, then retry | +| `DASHBOARD_CALL_ALREADY_IN_PROGRESS` | **Another call is already running.** Vapi can run one browser call at a time. | End the current browser call, then start this one again. | Correct, then retry | +| `DASHBOARD_INPUT_INVALID` | **Check the information you entered.** Some information in this request isn’t valid. | Correct the fields named in the error, then try again. | Correct, then retry | +| `DASHBOARD_NETWORK_ERROR` | **Connection interrupted.** We didn’t receive a response. | Check your connection, then try again. | Reconnect, then retry | +| `DASHBOARD_NETWORK_OFFLINE` | **You’re offline.** This device isn’t connected to the internet. | Check your internet connection, then try again. | Reconnect, then retry | +| `DASHBOARD_PERMISSION_DENIED` | **You don’t have permission.** Your account can’t complete this action. | Ask an organization admin for access, or switch to an organization where you have access. | Follow the next step first | +| `DASHBOARD_REQUEST_THROTTLED` | **Too many requests.** Vapi received too many requests in a short time. | Wait a moment, then try again. | Wait, then retry | +| `DASHBOARD_RESOURCE_NOT_FOUND` | **This item is no longer available.** It may have been deleted, or you may no longer have access. | Refresh the page. If it’s still missing, choose another item. | Follow the next step first | +| `DASHBOARD_SERVER_ERROR` | **Vapi hit a temporary problem.** The server couldn’t complete that action. | Try again. If this keeps happening, contact support and include the request ID. | Retry now | +| `DASHBOARD_TARGET_AUTHENTICATION_FAILED` | **Connected service rejected the request.** The connected service didn’t authorize this request. | Check the connected service credentials and permissions, then try again. | Correct, then retry | +| `DASHBOARD_UNKNOWN_ERROR` | **Something went wrong.** We couldn’t complete that action. | Try again. If this keeps happening, contact support. | Retry now | + +## Billing add-ons + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `BILLING_ADD_ON_PARTIAL_SUCCESS` | **Some add-on changes were saved.** Vapi saved some add-on changes, but others did not finish. The saved changes are already reflected below. | Review the saved and remaining changes, then retry only the changes that did not apply. | Retry only unfinished changes | +| `BILLING_ADD_ON_REVIEW_REQUIRED` | **Review the updated add-on changes.** Your saved add-ons changed since the last attempt, so the remaining charge or refund may be different. | Review the updated purchase or refund summary, then confirm again. Nothing was changed by this check. | Follow the next step first | +| `BILLING_ADD_ON_STATUS_UNKNOWN` | **Check which add-ons changed.** We could not confirm the saved add-on settings after this attempt. | Check the saved add-ons again before retrying so you do not repeat a charge or refund. | Follow the next step first | +| `BILLING_ADD_ON_UPDATE_FAILED` | **Could not update add-ons.** The add-on changes were not saved. Your requested changes are still here. | Review the remaining changes, then try them again. | Retry now | + +## Auto reload + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `BILLING_AUTO_RELOAD_AUTHENTICATION_REQUIRED` | **Auto reload is on—make a verified credit purchase.** Your auto reload settings were saved, but the automatic credit purchase couldn’t finish because your bank requires verification. | Use Buy more credits at the top of this page to make a separate, one-time purchase and complete bank verification. Don’t submit these auto reload settings again. | Follow the next step first | +| `BILLING_AUTO_RELOAD_BUSY` | **Billing operation in progress.** Another billing operation is still finishing for this account. | Your entries are still here. Wait a moment, then try saving again. | Wait, then retry | +| `BILLING_AUTO_RELOAD_CHARGE_FAILED` | **Auto reload is on, but the first reload failed.** Your auto reload settings were saved, but the immediate credit purchase failed. Your card wasn’t charged, and no credits were added. | Review your payment method, then use Buy more credits to make a separate, one-time purchase. Don’t submit these auto reload settings again. | Complete recovery first | +| `BILLING_AUTO_RELOAD_CHARGE_STATUS_UNKNOWN` | **Auto reload is on—check the first reload.** Your auto reload settings were saved, but we couldn’t confirm whether your card was charged or the credits were added. | Check your credit balance and payment history. If they don’t match, contact support and include the request ID. Don’t buy credits or submit these settings again until the first reload is confirmed. | Follow the next step first | +| `BILLING_AUTO_RELOAD_CHARGE_UNAVAILABLE` | **Auto reload is on, but the first reload didn’t complete.** Your auto reload settings were saved, but a billing service problem stopped the immediate credit purchase. Your card wasn’t charged, and no credits were added. | Contact support and include the request ID. Don’t submit these auto reload settings again. | Follow the next step first | +| `BILLING_AUTO_RELOAD_CONFLICT` | **Auto reload changed elsewhere.** Your changes weren’t saved because auto reload changed somewhere else. | Review the current settings. If they don’t look up to date, refresh the page before trying your change again. | Correct, then retry | +| `BILLING_AUTO_RELOAD_STATUS_UNKNOWN` | **Check whether auto reload changed.** We couldn’t confirm whether your auto reload settings were saved. | Check the saved settings before submitting again so you don’t trigger the same reload twice. | Follow the next step first | +| `BILLING_AUTO_RELOAD_UPDATE_FAILED` | **Couldn’t update auto reload.** Your auto reload settings weren’t changed. Your entries are still here. | Review the reload amount, threshold, and payment method, then try again. | Correct, then retry | + +## Coupons + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `BILLING_COUPON_ALREADY_REDEEMED` | **This coupon was already applied.** This subscription has already received this coupon. | No retry is needed. Check your credit balance or current plan for the coupon benefit. | Follow the next step first | +| `BILLING_COUPON_BUSINESS_EMAIL_REQUIRED` | **Use a business billing email.** This coupon can’t be redeemed with the current personal billing email. | Update the billing email to your work address, then try the same code again. | Correct, then retry | +| `BILLING_COUPON_EXPIRED` | **This coupon is no longer available.** The coupon expired or has reached its redemption limit. | Use a different coupon. If you think this is a mistake, contact support. | Follow the next step first | +| `BILLING_COUPON_INVALID` | **Coupon code not recognized.** We couldn’t find an active coupon with this code. | Check the code for typos, then try again. If the code came from Vapi, ask the sender to confirm it. | Correct, then retry | +| `BILLING_COUPON_ORGANIZATION_INELIGIBLE` | **This coupon isn’t available for this organization.** The coupon is limited to selected organizations, and this one isn’t included. | Switch to an eligible organization or use a different coupon. | Follow the next step first | +| `BILLING_COUPON_PAYMENT_METHOD_REQUIRED` | **Add a payment method first.** This plan coupon needs a payment method for usage beyond its included limits. | Add or update the payment method, then try the same code again. | Correct, then retry | +| `BILLING_COUPON_PLAN_INELIGIBLE` | **This coupon doesn’t work with your current plan.** This coupon is only available for pay-as-you-go subscriptions. | Switch to an eligible plan or use a coupon made for this subscription. | Correct, then retry | +| `BILLING_COUPON_UNAVAILABLE` | **Couldn’t apply this coupon.** A temporary Vapi problem stopped coupon redemption. The code is still here. | Check your balance and plan first. If the coupon was not applied, wait a moment, then try again. | Wait, then retry | + +## Billing details and documents + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `BILLING_CREDIT_PURCHASE_FAILED` | **Couldn’t purchase credits.** The credit purchase didn’t complete. Your amount is still here. | Review the amount and payment method, then try again. | Correct, then retry | +| `BILLING_EMAIL_REQUIRED` | **Add a billing email first.** A billing email is required before this payment method can be saved. | Save a valid billing email, then try the card again. | Correct, then retry | +| `BILLING_EMAIL_STATUS_UNKNOWN` | **Check whether the billing email was saved.** We couldn’t confirm whether the billing email update finished. | Check the saved billing email before trying again. | Follow the next step first | +| `BILLING_EMAIL_UPDATE_FAILED` | **Couldn’t save the billing email.** The billing email wasn’t saved. The email you entered is still here. | Wait a moment, then try saving the same email again. | Wait, then retry | +| `BILLING_HISTORY_LOAD_FAILED` | **Couldn’t load payment history.** Payment history is temporarily unavailable. Your billing information was not changed. | Try loading it again. If this keeps happening, contact support and include the request ID. | Wait, then retry | +| `BILLING_INVOICE_INFORMATION_SAVE_FAILED` | **Couldn’t save billing information.** The saved billing information wasn’t changed. Your entries are still here. | Try saving the same information again. You can also turn off saving and download the PDF without changing the saved defaults. | Wait, then retry | +| `BILLING_PDF_GENERATION_FAILED` | **Couldn’t prepare the PDF.** The PDF wasn’t created. Your billing information and payment history weren’t changed. | Try preparing it again. If it keeps failing, contact support. | Retry now | + +## Subscription plans + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `BILLING_PLAN_CONFLICT` | **The subscription changed.** The subscription changed after you opened this plan change. The selected plan is not currently active. | Review the latest plan and cost before trying again. | Correct, then retry | +| `BILLING_PLAN_INVALID_TRANSITION` | **This plan change is no longer available.** The selected change is not available for the subscription’s current plan. We did not change the plan. | Review the current plan and choose an available option. | Correct, then retry | +| `BILLING_PLAN_NOT_FOUND` | **We couldn’t find this subscription.** We couldn’t find the subscription for this plan change. | Refresh billing. If the subscription is still missing, contact support and include the request ID. | Follow the next step first | +| `BILLING_PLAN_STATUS_UNKNOWN` | **Check the current plan before trying again.** We couldn’t confirm the current plan or whether a charge or refund was completed. | Check the current plan and credit balance. Don’t try this plan change again until both are confirmed. | Follow the next step first | + +## Payment-method setup + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `BILLING_PAYMENT_METHOD_CORRECTION_REQUIRED` | **Review the card details.** The card details need a correction before this payment method can be saved. | Review the card number, expiry date, security code, and billing postal code, then try again. | Correct, then retry | +| `BILLING_PAYMENT_METHOD_REQUIRED` | **Add a payment method.** This payment can’t start because the subscription doesn’t have a usable payment method. | Add or update the payment method, then return here and try again. | Correct, then retry | +| `BILLING_PAYMENT_METHOD_STATUS_UNKNOWN` | **Check whether the payment method was saved.** We couldn’t confirm whether the payment method update finished. | Check the saved payment method before trying again. | Follow the next step first | +| `BILLING_PAYMENT_METHOD_UNAVAILABLE` | **Payment method setup is unavailable.** A billing service problem stopped this payment method update. | Wait a moment, then try the same card again. | Wait, then retry | +| `BILLING_PAYMENT_METHOD_UPDATE_FAILED` | **Couldn’t save the payment method.** The payment method wasn’t saved. | Review the card details or use another card, then try again. | Correct, then retry | +| `BILLING_PAYMENT_METHOD_VERIFICATION_CANCELED` | **Card verification was canceled.** The card was not saved because bank verification was canceled. | Start the card update again when you are ready to verify it. | Retry now | +| `BILLING_PAYMENT_METHOD_VERIFICATION_FAILED` | **Card verification failed.** The bank couldn’t verify this card, so it wasn’t saved. | Review the card details and billing postal code. If they look right, contact your bank or use another card, then try again. | Correct, then retry | +| `BILLING_PAYMENT_METHOD_VERIFICATION_INCOMPLETE` | **Finish verifying the card.** The card is still waiting for bank verification. | Complete any open bank verification. If it closed, save the same card again. | Correct, then retry | + +## Checkout and payment recovery + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `BILLING_PAST_DUE_RETRY_FAILED` | **Couldn’t complete this payment.** This past-due payment is still unpaid. | Review the payment method, then try the payment again. | Correct, then retry | +| `BILLING_PAYMENT_AUTHENTICATION_FAILED` | **Payment verification failed.** The bank couldn’t verify this payment. Your card wasn’t charged, and no credits were added. | Update the payment method or contact your bank, then start a new attempt. | Correct, then retry | +| `BILLING_PAYMENT_AUTHENTICATION_INCOMPLETE` | **Payment verification wasn’t completed.** The payment is still waiting for bank verification. | Continue verification to finish this payment. Don’t start a new payment. | Complete recovery first | +| `BILLING_PAYMENT_AUTHENTICATION_REQUIRED` | **Verify this payment.** Your bank requires an extra verification step before the payment can finish. | Complete the verification window. If it closed, continue verification here. | Complete recovery first | +| `BILLING_PAYMENT_BUSY` | **Another billing operation is finishing.** A credit or payment update is already in progress for this subscription. | Your entries are still here. Wait a moment, then retry the same payment attempt. Vapi will check its current status before continuing. | Wait, then retry | +| `BILLING_PAYMENT_CHECKOUT_VERIFICATION_UNAVAILABLE` | **Secure checkout isn’t ready.** This checkout action wasn’t sent because this browser couldn’t complete the secure checkout check. Any saved payment attempt is unchanged. | Wait a moment, then try this same payment attempt again. If it keeps happening, refresh the page. | Wait, then retry | +| `BILLING_PAYMENT_DECLINED` | **Your bank declined this payment.** The payment didn’t go through. Your card wasn’t charged, and no credits were added. | Review or replace the payment method. You can also contact your bank, then try again. | Correct, then retry | +| `BILLING_PAYMENT_IDEMPOTENCY_CONFLICT` | **This payment attempt changed.** This payment key was already used for different payment details. | Refresh billing, review the current payment status, then start a new attempt. | Correct, then retry | +| `BILLING_PAYMENT_INVALID_AMOUNT` | **Enter a valid credit amount.** The purchase amount must be between $1 and $999,999, with no more than two decimal places. No payment was started. | Enter an amount in that range with no more than two decimal places, then try again. | Correct, then retry | +| `BILLING_PAYMENT_NOT_FOUND` | **This payment is no longer available.** We couldn’t find the payment you tried to recover. | Refresh payment history. If it’s still missing, contact support and include the request ID. | Follow the next step first | +| `BILLING_PAYMENT_NOT_PAST_DUE` | **This payment no longer needs a retry.** The payment status changed after you opened it. | Refresh payment history to see its current status before taking another action. | Follow the next step first | +| `BILLING_PAYMENT_RECOVERY_CLEANUP_UNAVAILABLE` | **Payment completed — refresh billing.** The payment finished, but this browser couldn’t remove its saved recovery key. | Refresh billing before starting another payment. Vapi will verify the completed attempt and clear it when storage is available. | Complete recovery first | +| `BILLING_PAYMENT_RECOVERY_RESET_UNAVAILABLE` | **Refresh before another payment.** This payment attempt finished, but this browser couldn’t remove its saved recovery key. | Allow site storage, then refresh billing before starting another payment. | Complete recovery first | +| `BILLING_PAYMENT_RECOVERY_STORAGE_UNAVAILABLE` | **Allow browser storage to start this payment.** No payment request was sent because this browser couldn’t save the recovery key needed to prevent duplicate charges. | Allow site storage for Vapi or use a supported browser, then try the payment again. | Correct, then retry | +| `BILLING_PAYMENT_REVIEW_REQUIRED` | **This older payment needs review.** We can’t safely retry this older payment because its provider status can’t be verified. No new payment was started. | Contact support with the payment ID before trying again. | Follow the next step first | +| `BILLING_PAYMENT_STATUS_UNKNOWN` | **Check this payment before trying again.** We couldn’t confirm whether the payment finished or credits were added. | Check the payment status here. Don’t start another payment until this one is confirmed. | Follow the next step first | +| `BILLING_PAYMENT_UNAVAILABLE` | **Billing is temporarily unavailable.** A Vapi billing problem stopped the payment. Your card wasn’t charged, and no credits were added. | Contact support and include the request ID before starting another payment. | Follow the next step first | + +## Phone numbers + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `PHONE_NUMBER_ALREADY_IN_USE` | **This phone number is already in use.** This organization already has a phone number with that number or SIP identifier. | Open the existing phone number, or use a different number or identifier. | Correct, then retry | +| `PHONE_NUMBER_CREATE_FAILED` | **Couldn’t create phone number.** The phone number wasn’t created. Your entries are still here. | Review your entries, then try again. | Retry now | +| `PHONE_NUMBER_DELETE_FAILED` | **Couldn’t delete phone number.** The phone number is still available in this organization. | Try again. If this keeps happening, contact support. | Retry now | +| `PHONE_NUMBER_FORMAT_INVALID` | **Check the phone number format.** The phone number or SIP identifier does not match the required format. | Use international E.164 format with a country code, such as +14155551234, or correct the SIP identifier, then try again. | Correct, then retry | +| `PHONE_NUMBER_IMPORT_FAILED` | **Couldn’t import phone number.** The phone number wasn’t imported. Your entries are still here. | Review your entries, then try again. | Retry now | +| `PHONE_NUMBER_LIMIT_REACHED` | **Phone number limit reached.** This organization has reached its phone number limit. | Remove a phone number you no longer need, or contact support to request a higher limit. | Correct, then retry | +| `PHONE_NUMBER_PROVIDER_ACCESS_FAILED` | **Couldn’t verify provider access.** Vapi couldn’t verify this number with the selected provider credential. | Confirm the number belongs to this provider account and that the credential is current, then try again. | Correct, then retry | +| `PHONE_NUMBER_PROVIDER_UNAVAILABLE` | **Phone number provider is unavailable.** The selected phone number provider didn’t complete the request. | Wait a moment, then try again. | Wait, then retry | +| `PHONE_NUMBER_REGION_UNSUPPORTED` | **This region isn’t supported.** Vapi can’t provide this type of phone number in the selected region. | Choose a supported number type or region, then try again. | Correct, then retry | +| `PHONE_NUMBER_UPDATE_FAILED` | **Couldn’t update phone number.** The phone number wasn’t updated. Your changes are still here. | Review your changes, then try again. | Retry now | + +## Tools + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `TOOL_CREATE_FAILED` | **Couldn’t create the tool.** The tool wasn’t created. | Review the tool settings, then try again. | Correct, then retry | +| `TOOL_DELETE_FAILED` | **Couldn’t delete the tool.** The tool is still available. | Try again. If this keeps happening, contact support. | Retry now | +| `TOOL_DISCOVERY_FAILED` | **Couldn’t load tools from this MCP server.** The saved MCP server didn’t return its tools. | Check the saved server URL and authentication, then refresh. | Correct, then retry | +| `TOOL_DUPLICATE_FAILED` | **Couldn’t duplicate the tool.** No copy was created. | Try again. If this keeps happening, contact support. | Retry now | +| `TOOL_SCHEMA_PROPERTY_NAME_INVALID` | **Property name can’t contain spaces.** Tool schema property names can’t contain spaces. | Replace each space with an underscore or hyphen, then try again. | Correct, then retry | +| `TOOL_TEST_FAILED` | **Couldn’t test the tool.** The test request didn’t complete. | Check the tool configuration, then try the test again. | Correct, then retry | +| `TOOL_UPDATE_FAILED` | **Couldn’t update the tool.** We couldn’t save your changes. Your changes are still here. | Try again. If this keeps happening, contact support. | Retry now | + +## Workflows + +| Code | What happened | What to do | Retry | +|---|---|---|---| +| `WORKFLOW_CONNECTION_INVALID` | **Connection needs attention.** A connection points to a node that is no longer in this workflow. | Remove the affected connection below, then save again. | Correct, then retry | +| `WORKFLOW_DELETE_FAILED` | **Couldn’t delete the workflow.** The workflow is still available. | Try again. If this keeps happening, contact support. | Retry now | +| `WORKFLOW_LOAD_FAILED` | **Couldn’t load the workflow.** The workflow editor couldn’t load this workflow. | Try again. If it’s still unavailable, return to Workflows and open it again. | Retry now | +| `WORKFLOW_REMOTE_CHANGE_DETECTED` | **This workflow changed elsewhere.** The saved workflow changed after you opened it. Your unsaved edits are still here. | Save to replace the saved version with this draft, or discard this draft and use the latest saved version below. | Correct, then retry | +| `WORKFLOW_RUN_FAILED` | **Couldn’t run the test call.** The test call didn’t complete. Your variable values are still here. | Review the workflow configuration, then try the call again. | Correct, then retry | +| `WORKFLOW_SAVE_FAILED` | **Couldn’t save the workflow.** Your changes weren’t saved. Your graph and edits are still here. | Review the workflow configuration, then save again. | Retry now | + +## Related references + +- [Understand errors and recovery actions](/errors) +- [Handle API validation errors](/errors/validation-errors) +- [Troubleshoot custom tools](/tools/custom-tools-troubleshooting) +- [Report an issue safely](/issue-reporting) diff --git a/fern/errors/index.mdx b/fern/errors/index.mdx new file mode 100644 index 000000000..b996566bb --- /dev/null +++ b/fern/errors/index.mdx @@ -0,0 +1,86 @@ +--- +title: Understand and recover from errors +subtitle: Find the next safe action, technical details, and the information support needs +slug: errors +--- + +When an action fails, start with the message beside that action. It explains what happened and what to do next in the context of your current task. + +If the first step does not solve the problem, use the technical details to identify the error without sharing sensitive data. + + + + Correct the named field or setting, reconnect, wait, or retry only when the message says it is safe. + + + In the dashboard, open **Technical details**. For an API request, copy `code` from the response body. The stable code identifies the error even if its displayed wording changes. + + + In the dashboard, copy the request ID from **Technical details** if one is shown. For an API request, copy the `X-Request-ID` response header. Save it before refreshing the page. + + + +## Choose the right reference + + + + Look up a stable code and find its meaning, recovery action, and retry guidance. + + + Handle field-level validation issues while keeping compatibility with the legacy response fields. + + + Understand why a call ended and whether the ending was expected or caused by a call-lifecycle failure. + + + + +An `endedReason` describes the result of a call. It is different from a dashboard diagnostic code or an HTTP API error. + + +## Decide what to do next + +| The message says to... | What that means | +|---|---| +| Correct something | Change the named field, credential, permission, or account state before trying again. | +| Retry | The same action is safe to repeat. | +| Wait and retry | The problem may be temporary. Wait briefly before another attempt. | +| Check the saved state | The result is uncertain or partially complete. Confirm what changed before repeating the action. | +| Contact support | Do not keep retrying. Send the diagnostic code and request ID through a support channel. | + +## Request IDs + +A request ID is a correlation label for one request. It is not a password, API key, or proof of identity. + +For API requests, copy the `X-Request-ID` response header. A structured error response may also include the same value in `requestId`: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +X-Request-ID: req_01JEXAMPLE +``` + +```json +{ + "code": "VALIDATION_FAILED", + "requestId": "req_01JEXAMPLE" +} +``` + +The response header is the best place to look because it is available even when a client cannot parse the response body. + +### What to include in a support report + +- Request ID +- Diagnostic code, if shown +- Date, time, and timezone +- The dashboard action you took, or the API method and endpoint +- HTTP status, if this was an API request +- What you expected and what happened instead +- Call ID, if the problem happened during a call + + +Never share API keys, `Authorization` headers, access tokens, provider credentials, full payment-card details, or request payloads that contain secrets. A request ID is enough for Vapi to correlate the request. + + +See [How to Report Issues Effectively](/issue-reporting) for report templates and support options. diff --git a/fern/errors/validation-errors.mdx b/fern/errors/validation-errors.mdx new file mode 100644 index 000000000..4fc32801b --- /dev/null +++ b/fern/errors/validation-errors.mdx @@ -0,0 +1,85 @@ +--- +title: Fix API validation errors +subtitle: Find invalid fields with stable codes while keeping older clients working +slug: errors/validation-errors +--- + +When Vapi rejects an API request because a field is missing or invalid, the response can identify the field, explain the problem, and tell you what to correct. + + +The structured contract on this page covers request DTO validation. Other API errors, including some HTTP 400 responses, may use a different shape. + + +## Response shape + +```json +{ + "statusCode": 400, + "message": ["name must be a string"], + "error": "Bad Request", + "type": "urn:vapi:problem:validation-failed", + "title": "Request validation failed", + "status": 400, + "detail": "Fix the fields listed below and try again.", + "code": "VALIDATION_FAILED", + "errors": [ + { + "code": "INVALID_TYPE", + "message": "name must be a string", + "pointer": "/body/name" + } + ], + "requestId": "req_01JEXAMPLE" +} +``` + +The response remains `application/json`. The `X-Request-ID` response header is the primary request identifier; `requestId` may also be present in the structured body. + +## Fields to use + +| Field | Purpose | +|---|---| +| `code` | Stable top-level category. For this response, it is `VALIDATION_FAILED`. | +| `errors[].code` | Stable reason for one field issue. Branch application logic on this value instead of the message text. | +| `errors[].pointer` | JSON Pointer to the invalid input. Use it to associate the issue with a form field or request property. | +| `errors[].message` | Human-readable explanation. Display it to a developer, but do not parse it for application logic. | +| `detail` | Plain-language recovery guidance for the request as a whole. | +| `requestId` | Optional body copy of the request correlation ID. Prefer the `X-Request-ID` response header when available. | + +## Field issue codes + +| Code | Meaning | Correction | +|---|---|---| +| `FIELD_NOT_ALLOWED` | The request includes a field that this endpoint does not accept. | Remove the field. | +| `FIELD_REQUIRED` | A required value is missing or empty, or a required set has no supplied value. | Add the required field or provide at least one accepted value. | +| `INVALID_CHOICE` | The value is not one of the allowed choices. | Use a documented choice. | +| `INVALID_FORMAT` | The value has the wrong format. | Match the documented format, such as a UUID or URL. | +| `INVALID_SCHEMA` | An object or nested value does not match the expected schema. | Compare the value with the endpoint schema and correct its structure. | +| `INVALID_TYPE` | The value has the wrong JSON type. | Send the documented string, number, boolean, array, or object type. | +| `INVALID_VALUE` | The value is not valid for this field. | Replace it with a valid value. | +| `OUT_OF_RANGE` | A number, length, or count is outside the accepted range. | Use a value within the documented limits. | + +## Locate the invalid input + +Pointers follow JSON Pointer notation and begin with the request location: + +| Pointer | Location | +|---|---| +| `/body/name` | The `name` property in the JSON request body. | +| `/query/search` | The `search` query parameter. | +| `/param/id` | The `id` path parameter. | +| `/input/0/name` | The `name` property in the first item of an input array. | + +Nested properties and array indexes continue as additional pointer segments. JSON Pointer escapes `~` as `~0` and `/` as `~1` inside a property name. + +## Client handling + +1. If `code` is `VALIDATION_FAILED` and `errors` is present, group the issues by `pointer`. +2. Use each issue `code` to choose behavior; show its `message` as supporting context. +3. Keep a fallback for the legacy `statusCode`, `message`, and `error` fields. +4. Preserve the `X-Request-ID` header so logs and support reports can identify the request. +5. Retry only after correcting the reported fields. + +The legacy fields remain available during the additive rollout. No removal date is currently published, so clients should keep the fallback until a future compatibility notice says otherwise. + +For other dashboard and product codes, see the [diagnostic code reference](/errors/diagnostic-codes). diff --git a/fern/issue-reporting.mdx b/fern/issue-reporting.mdx index 5863df5a2..30ddbfad5 100644 --- a/fern/issue-reporting.mdx +++ b/fern/issue-reporting.mdx @@ -9,6 +9,12 @@ To help us assist you as quickly and accurately as possible, it's essential to p This guide will help you structure your reports to get the best support experience. + +Never include API keys, `Authorization` headers, access tokens, provider credentials, full payment-card details, or payloads that contain secrets. Redact sensitive information from screenshots, recordings, and console output. Share account information only by email at support@vapi.ai or through your dedicated enterprise support channel—not in public Discord channels or the public roadmap. + + +If an error shows **Technical details**, include its diagnostic code and request ID. See [Request IDs](/errors#request-ids) for where to find one and why it is safe to share. + ## Types of Issues We handle three main categories of issues. Choose the appropriate category and follow the specific guidelines for faster resolution: @@ -105,6 +111,7 @@ For problems with the Vapi dashboard interface, configuration screens, or any vi - **Steps to reproduce** the issue - **Console errors** (if any - press F12 to open developer tools) - **URL** where the issue occurs +- **Diagnostic code and request ID**, if shown ### Creating Effective Screen Recordings @@ -146,10 +153,11 @@ For issues related to your account, billing, login, or organization settings, pr ### Required Information -- **Email address** used for your account login +- **Email address** used for your account login, shared through a private support channel - **Organization ID** (for organization-level inquiries) - **Detailed description** of the issue - **Screenshots** of error messages or unexpected behavior +- **Diagnostic code and request ID**, if shown ### Finding Your Organization ID @@ -180,9 +188,9 @@ Use this checklist to ensure you're providing the right information for your iss |------------|---------------------| | Assistant behavior problems | Call ID, timestamp, issue description, expected behavior, screen recording | | Call connection failures | Call ID only | -| Dashboard/UI issues | Screen recording, browser info, steps to reproduce, console errors | -| Login or authentication | Email address, screenshots of errors | -| Account upgrades or billing | Organization ID, email address, error screenshots | +| Dashboard/UI issues | Screen recording, browser and OS, URL, steps to reproduce, console errors, diagnostic code and request ID | +| Login or authentication | Email address in a private support channel, error screenshot, diagnostic code and request ID | +| Account upgrades or billing | Organization ID, email address in a private support channel, error screenshot, diagnostic code and request ID | | Feature requests | Detailed description of desired functionality | ## Best Practices diff --git a/fern/support.mdx b/fern/support.mdx index 0a05770a2..2c983fc80 100644 --- a/fern/support.mdx +++ b/fern/support.mdx @@ -10,6 +10,10 @@ slug: support We offer multiple ways to get support with your Vapi projects: + +If an error brought you here, open [Errors and troubleshooting](/errors) first. Follow the recovery step, then include the diagnostic code and request ID if you contact support. Send account details only to support@vapi.ai or your dedicated enterprise support channel. Do not post them in public Discord channels or the public roadmap. Redact secrets from screenshots, recordings, and console output. + + Email support@vapi.ai with your request and our team will get back to you promptly. @@ -63,6 +67,14 @@ We actively monitor and prioritize feature requests based on user votes and feed Access helpful reference materials to better understand Vapi's platform and get answers to common questions: + + Look up diagnostic codes, API validation errors, and request-ID guidance. + + +If a dashboard action shows a stable code such as `TOOL_CREATE_FAILED`, `TOOL_DISCOVERY_FAILED`, or `TOOL_TEST_FAILED`, use the [tool section of the diagnostic code reference](/errors/diagnostic-codes#tools) for the immediate recovery and retry guidance. The sections below cover tool behavior during assistant calls. + + **In this guide, you'll learn to:** - Diagnose why tools aren't triggering