Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.kallglot.com/llms.txt

Use this file to discover all available pages before exploring further.

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

CodeDescription
200Success
201Created
202Accepted
400Invalid request
401Authentication failed
402Payment required or API credits exhausted
403Permission denied or inactive organization
404Resource not found
502Upstream gateway error (for example SIP dial failed)
409Conflict
422Request validation failed before handler execution
429Rate limit exceeded
500Server error
503Temporary 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"
  }
}
FieldDescription
typeHigh-level error category
codeMachine-readable error code
messageHuman-readable explanation
paramRequest field related to the error, when available
request_idRequest identifier for support and debugging
retry_afterRetry delay in seconds for retryable limit/conflict errors

Useful Error Headers

HeaderWhen PresentDescription
X-Request-IDAPI V1 HTTP responsesRequest identifier
Retry-After429 and some 409 responsesSeconds to wait before retrying
X-API-Credits-RemainingAuthenticated HTTP responsesRemaining API credits
X-API-Credits-UsedAuthenticated HTTP responsesCredits used this billing period

Error Types

authentication_error

CodeStatusDescription
api_key_invalid401API key is missing, malformed, or unknown
api_key_expired401API key has expired
api_key_revoked401API key has been revoked
api_key_wrong_environment401Test/live key used in the wrong environment
stream_token_invalid401Stream token is invalid or expired

permission_error

CodeStatusDescription
organization_inactive403Organization subscription is inactive
insufficient_api_credits402Organization has no API credits remaining
insufficient_permissions403API key lacks required permission
ai_agent_disabled403AI agent mode is not enabled
override_not_allowed403Requested AI override field is not allowed
recording_not_permitted403Recording access is disallowed by policy
consent_required403Recording access requires missing consent

invalid_request_error

CodeStatusDescription
idempotency_mismatch400Same idempotency key reused with a different body
unsupported_mode400Session mode is not supported
transcript_not_available400Transcript is not available for analysis
validation_error400Request body is syntactically valid but semantically invalid
invalid_audio_format400WebSocket audio format is unsupported
routing_failed400Telephony routing could not be resolved. See the docs_url in the error response for specific guidance.
sip_not_enabled400SIP routing is not enabled. Enable SIP in the Telephony section of the Developer Portal.
session_not_dialable400Session cannot be dialed or hung up in its current state
no_default_provider400No provider connection can be resolved. Add a provider connection or buy a managed number.
phone_number_not_found400The phone number is not a Kallglot-managed number for this organization
connection_not_found400The provider connection ID does not exist or is inactive
connection_invalid400The provider connection credentials are invalid or expired

conflict_error

CodeStatusDescription
session_already_ended409Session has already ended
idempotency_conflict409Matching request is still processing
stream_already_connected409Session already has an active stream

not_found_error

CodeStatusDescription
session_not_found404Session does not exist or is not owned by your org
recording_not_found404Recording does not exist
analysis_not_found404Analysis does not exist
agent_not_found404AI agent resource not found (Agents API)
ai_agent_not_found404Referenced AI agent ID could not be resolved for session creation

rate_limit_error

CodeStatusDescription
rate_limit_exceeded429Too many requests in the current window
concurrent_session_limit429Too many active sessions for the organization

api_error

CodeStatusDescription
internal_error500Unexpected error—retry or contact support with request_id
service_unavailable503Required dependency is temporarily unavailable (message may name a subsystem, e.g. billing). Retry with backoff; not a client or URL bug
freeswitch_unavailable503SIP dialing path temporarily unavailable
dial_failed502Outbound 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 TypeRetry?Guidance
rate_limit_errorYesWait for Retry-After or reset window
api_errorYesRetry with exponential backoff
conflict_errorSometimesRetry only when explicitly safe
invalid_request_errorNoFix the request first
authentication_errorNoCorrect the credentials or token
permission_errorNoFix billing, subscription, or permissions

WebSocket Close Codes

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

Common Issues

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