Error Codes

The Kallglot API returns structured JSON errors with machine-readable code and type fields.

In your integration, branch on HTTP status and error.code. Log error.message and request_id when you need support.

Avoid mixing up session fields: Create-session telephony belongs in routing. If you copy the provider string from a response or a webhook payload into your POST /v1/sessions body, the request will not match the API. Use Create Session and Telephony providers as the source of truth for request JSON.

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`202`	Accepted
`400`	Invalid request
`401`	Authentication failed
`402`	Payment required or API credits exhausted
`403`	Permission denied or inactive organization
`404`	Resource not found
`502`	Upstream gateway error (for example SIP dial failed)
`409`	Conflict
`422`	Request validation failed before handler execution
`429`	Rate limit exceeded
`500`	Server error
`503`	Temporary service outage

Error Response Format

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_api_credits",
    "message": "API credits exhausted. Purchase more credits to continue.",
    "request_id": "req_123"
  }
}

Field	Description
`type`	High-level error category
`code`	Machine-readable error code
`message`	Human-readable explanation
`param`	Request field related to the error, when available
`request_id`	Request identifier for support and debugging
`retry_after`	Retry delay in seconds for retryable limit/conflict errors

Useful Error Headers

Header	When Present	Description
`X-Request-ID`	API V1 HTTP responses	Request identifier
`Retry-After`	`429` and some `409` responses	Seconds to wait before retrying
`X-API-Credits-Remaining`	Authenticated HTTP responses	Remaining API credits
`X-API-Credits-Used`	Authenticated HTTP responses	Credits used this billing period

Error Types

authentication_error

Code	Status	Description
`api_key_invalid`	`401`	API key is missing, malformed, or unknown
`api_key_expired`	`401`	API key has expired
`api_key_revoked`	`401`	API key has been revoked
`api_key_wrong_environment`	`401`	Test/live key used in the wrong environment
`stream_token_invalid`	`401`	Stream token is invalid or expired

permission_error

Code	Status	Description
`organization_inactive`	`403`	Organization subscription is inactive
`insufficient_api_credits`	`402`	Organization has no API credits remaining
`insufficient_permissions`	`403`	API key lacks required permission
`ai_agent_disabled`	`403`	AI agent mode is not enabled
`override_not_allowed`	`403`	Requested AI override field is not allowed
`recording_not_permitted`	`403`	Recording access is disallowed by policy
`consent_required`	`403`	Recording access requires missing consent

invalid_request_error

Code	Status	Description
`idempotency_mismatch`	`400`	Same idempotency key reused with a different body
`unsupported_mode`	`400`	Session mode is not supported
`transcript_not_available`	`400`	Transcript is not available for analysis
`validation_error`	`400`	Request body is syntactically valid but semantically invalid
`invalid_audio_format`	`400`	WebSocket audio format is unsupported
`routing_failed`	`400`	Telephony routing could not be resolved. See the `docs_url` in the error response for specific guidance.
`sip_not_enabled`	`400`	SIP routing is not enabled. Enable SIP in the Telephony section of the Developer Portal.
`session_not_dialable`	`400`	Session cannot be dialed or hung up in its current state
`no_default_provider`	`400`	No provider connection can be resolved. Add a provider connection or buy a managed number.
`phone_number_not_found`	`400`	The phone number is not a Kallglot-managed number for this organization
`connection_not_found`	`400`	The provider connection ID does not exist or is inactive
`connection_invalid`	`400`	The provider connection credentials are invalid or expired

conflict_error

Code	Status	Description
`session_already_ended`	`409`	Session has already ended
`idempotency_conflict`	`409`	Matching request is still processing
`stream_already_connected`	`409`	Session already has an active stream

not_found_error

Code	Status	Description
`session_not_found`	`404`	Session does not exist or is not owned by your org
`recording_not_found`	`404`	Recording does not exist
`analysis_not_found`	`404`	Analysis does not exist
`agent_not_found`	`404`	AI agent resource not found (Agents API)
`ai_agent_not_found`	`404`	Referenced AI agent ID could not be resolved for session creation

rate_limit_error

Code	Status	Description
`rate_limit_exceeded`	`429`	Too many requests in the current window
`concurrent_session_limit`	`429`	Too many active sessions for the organization

api_error

Code	Status	Description
`internal_error`	`500`	Unexpected error—retry or contact support with `request_id`
`service_unavailable`	`503`	Required dependency is temporarily unavailable (message may name a subsystem, e.g. billing). Retry with backoff; not a client or URL bug
`freeswitch_unavailable`	`503`	SIP dialing path temporarily unavailable
`dial_failed`	`502`	Outbound SIP dial attempt failed

Handling Errors

JavaScript

const response = await fetch('https://api.kallglot.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KALLGLOT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'bidirectional_translation',
    source_language: 'de',
    target_language: 'en'
  })
});

if (!response.ok) {
  const payload = await response.json();
  const error = payload.error;

  if (response.status === 402 && error.code === 'insufficient_api_credits') {
    console.error('Buy more API credits in the Developer Portal');
  } else if (response.status === 403 && error.code === 'organization_inactive') {
    console.error('Activate a subscription for this organization');
  } else if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') || '1');
    await sleep(retryAfter * 1000);
  } else {
    console.error(`${error.code}: ${error.message}`);
  }
}

Python

import requests
import time

response = requests.post(
    'https://api.kallglot.com/v1/sessions',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'mode': 'bidirectional_translation',
        'source_language': 'de',
        'target_language': 'en'
    }
)

if response.status_code == 402:
    error = response.json()['error']
    if error['code'] == 'insufficient_api_credits':
        print('Purchase more API credits in the Developer Portal')
elif response.status_code == 429:
    time.sleep(int(response.headers.get('Retry-After', '1')))
elif response.status_code >= 400:
    error = response.json().get('error', {})
    print(f"{error.get('code')}: {error.get('message')}")

Retry Guidance

Error Type	Retry?	Guidance
`rate_limit_error`	Yes	Wait for `Retry-After` or reset window
`api_error`	Yes	Retry with exponential backoff
`conflict_error`	Sometimes	Retry only when explicitly safe
`invalid_request_error`	No	Fix the request first
`authentication_error`	No	Correct the credentials or token
`permission_error`	No	Fix billing, subscription, or permissions

WebSocket Close Codes

Code	Meaning
`1000`	Normal close
`1001`	Going away
`1002`	Protocol error
`4001`	Invalid or expired stream token
`4004`	Session not found
`4009`	Stream already active
`4010`	Session already ended
`4029`	Rate limited
`4500`	Streaming connection closed after a server-side error

Common Issues

api_key_invalid

Cause: The API key is missing, malformed, or does not exist.What to do: Confirm the key starts with sk_live_ or sk_test_, pass it in Authorization: Bearer ..., and verify that the key still exists in the Developer Portal.

organization_inactive

Cause: The key is valid, but the owning organization does not have an active subscription.What to do: Activate or renew the organization subscription before retrying API requests.

insufficient_api_credits

Cause: The organization has exhausted its API credits.What to do: Purchase more API credits in the Developer Portal and retry the request. Check X-API-Credits-Remaining to monitor balances proactively.

rate_limit_exceeded

Cause: Too many requests were sent in the current window.What to do: Honor the Retry-After header, reduce concurrency, and implement backoff for automated clients.

session_not_found

Cause: The session ID does not exist or does not belong to the authenticated organization.What to do: Verify the sess_... id and ensure you are using an API key for the same organization that created the session.

sip_not_enabled

Cause: The session requested SIP routing but SIP is not enabled for this organization.What to do: Go to the Developer Portal > Telephony and enable SIP in the SIP / PBX section. Configure your allowed IPs before enabling.

no_default_provider

Cause: No telephony route could be resolved. You didn’t specify a phone number, connection ID, or SIP mode, and there’s no default provider connection configured.What to do: Either pass routing.phone_number for a Kallglot-managed number, routing.connection_id for an external provider, or routing.type: "sip" for SIP mode. Alternatively, set a default provider connection in the Developer Portal.

routing_failed

Cause: Telephony routing could not be resolved. This is a general routing error that includes specific guidance in the docs_url field of the error response.What to do: Check the docs_url in the error response for specific guidance. Common causes include:

No provider connection configured (use routing.connection_id)
Phone number not managed by your organization (verify in Developer Portal)
Ambiguous routing with multiple connections (specify routing.connection_id)
SIP mode requested but not enabled

connection_not_found

Cause: The provider connection ID specified in routing.connection_id doesn’t exist or has been deleted.What to do: Verify the connection ID in the Developer Portal > Telephony > External Provider Connections. Ensure the connection is active.

​Error Codes

​HTTP Status Codes

​Error Response Format

​Useful Error Headers

​Error Types

​authentication_error

​permission_error

​invalid_request_error

​conflict_error

​not_found_error

​rate_limit_error

​api_error

​Handling Errors

​JavaScript

​Python

​Retry Guidance

​WebSocket Close Codes

​Common Issues

Error Codes

HTTP Status Codes

Error Response Format

Useful Error Headers

Error Types

authentication_error

permission_error

invalid_request_error

conflict_error

not_found_error

rate_limit_error

api_error

Handling Errors

JavaScript

Python

Retry Guidance

WebSocket Close Codes

Common Issues