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