VapiAI · dev-seth-vapi · Jul 15, 2026
diff --git 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).
 </Note>
 
+<Info>
+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).
+</Info>
+
 ## 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
@@ -206,7 +206,7 @@ For any tool in your `Tools` section:
 | **Long silences** | Model processing delay | Use faster models or reduce response length |
 
 <Tip>
-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).
 </Tip>
 
 ## Getting help

diff --git 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
diff --git a/fern/errors/index.mdx 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.
+
+<Steps>
+  <Step title="Follow the recovery step">
+    Correct the named field or setting, reconnect, wait, or retry only when the message says it is safe.
+  </Step>
+  <Step title="Copy the diagnostic code">
+    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.
+  </Step>
+  <Step title="Save the request ID">
+    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.
+  </Step>
+</Steps>
+
+## Choose the right reference
+
+<CardGroup cols={3}>
+  <Card title="Dashboard diagnostic codes" icon="rectangle-code" href="/errors/diagnostic-codes">
+    Look up a stable code and find its meaning, recovery action, and retry guidance.
+  </Card>
+  <Card title="API validation errors" icon="brackets-curly" href="/errors/validation-errors">
+    Handle field-level validation issues while keeping compatibility with the legacy response fields.
+  </Card>
+  <Card title="Call ended reasons" icon="phone-slash" href="/calls/call-ended-reason">
+    Understand why a call ended and whether the ending was expected or caused by a call-lifecycle failure.
+  </Card>
+</CardGroup>
+
+<Note>
+An `endedReason` describes the result of a call. It is different from a dashboard diagnostic code or an HTTP API error.
+</Note>
+
+## 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
+
+<Warning>
+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.
+</Warning>
+
+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
@@ -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.
+
+<Note>
+The structured contract on this page covers request DTO validation. Other API errors, including some HTTP 400 responses, may use a different shape.
+</Note>
+
+## 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
@@ -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.
 
+<Warning>
+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.
+</Warning>
+
+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
@@ -10,6 +10,10 @@ slug: support
 
 We offer multiple ways to get support with your Vapi projects:
 
+<Info>
+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.
+</Info>
+
 <CardGroup cols={3}>
   <Card title="Email Support" icon="envelope" href="mailto:support@vapi.ai">
     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:
 
 <CardGroup cols={2}>
+  <Card
+    title="Errors and troubleshooting"
+    icon="triangle-exclamation"
+    href="/errors"
+  >
+    Look up diagnostic codes, API validation errors, and request-ID guidance.
+  </Card>
+
   <Card 
     title="Glossary" 
     icon="book"

diff --git a/fern/tools/custom-tools-troubleshooting.mdx b/fern/tools/custom-tools-troubleshooting.mdx
@@ -7,6 +7,10 @@ description: "Resolve common issues with custom tool integrations"
 
 Troubleshoot and fix common issues with custom tool integrations in your Vapi assistants.
 
+<Info>
+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.
+</Info>
+
 **In this guide, you'll learn to:**
 
 - Diagnose why tools aren't triggering