> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkarta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand API errors and troubleshoot requests.

Use the HTTP status first, then the error body. Error fields differ by endpoint and by whether a failure occurs during authentication or request processing.

| Status | What to do |
| - | - |
| `400` | Correct the query/body or address the reported account configuration issue. |
| `401` | Include a valid API key in the `Authorization` header. |
| `403` | Check that you have access to the requested operation. |
| `402` | On web-call creation, check credit balance before retrying. |
| `404` | Verify the resource identifier and account ownership; a session also requires a live voice agent. |
| `409` | For deduplicated voice creation, check whether the request is still in progress or the same request ID was reused with a different body. |
| `422` | Correct the invalid fields described by the endpoint's validation response. |
| `500`, `503` | Save the request ID. Apply the endpoint's retry rules; a failure does not guarantee that no side effect occurred. |

## Authentication errors

Authentication failures return JSON with a machine-readable `code` and an `instance` containing the request identifier:

```json theme={null}
{
  "type": "https://httpstatus.es/401",
  "title": "Invalid API Key",
  "status": 401,
  "detail": "API key is required",
  "instance": "example-request-001",
  "code": "invalid_api_key"
}
```

## Error formats

Error fields vary by endpoint. Check its response schema for the complete format.

| Error format | Fields |
| - | - |
| Voice errors (`application/problem+json`) | `type`, `title`, `status`, `detail`, `instance`, `trace_id` |
| WebSocket session errors | `code`, `traceId`, and error details |
| Account and billing errors | `error`, sometimes `message` |
| Request validation errors | `message`, sometimes an `errors` array |
| Connection errors | `error` and `message` |

Use the HTTP status code and save `X-Request-ID` for troubleshooting.

## Reporting an issue

Include the request ID, HTTP method and path, timestamp, status, and a redacted error body. Never include your API key, connection tokens, or private recording links.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.