Errors - Karta API

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:

{
  "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.