Error Codes
The Kallglot API uses conventional HTTP response codes and returns detailed error information in JSON format.HTTP Status Codes
| Code | Description |
|---|---|
200 | Success |
201 | Created |
202 | Accepted (async processing) |
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Invalid or missing API key |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource doesn’t exist |
409 | Conflict - Resource already exists |
422 | Unprocessable Entity - Validation failed |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error |
502 | Bad Gateway - Upstream service error |
503 | Service Unavailable - Temporary outage |
Error Response Format
All errors follow this structure:| Field | Description |
|---|---|
code | Machine-readable error code |
message | Human-readable error description |
type | Error category |
param | The parameter that caused the error (if applicable) |
doc_url | Link to documentation about this error |
Error Types
authentication_error
Problems with API authentication.| Code | Description |
|---|---|
invalid_api_key | The API key is malformed or doesn’t exist |
expired_api_key | The API key has expired |
revoked_api_key | The API key has been revoked |
invalid_token | WebSocket or session token is invalid |
expired_token | Token has expired |
authorization_error
The API key is valid but lacks permissions.| Code | Description |
|---|---|
insufficient_permissions | API key lacks required permissions |
organization_suspended | Organization account is suspended |
feature_not_available | Feature not available on your plan |
validation_error
Request validation failed.| Code | Description |
|---|---|
invalid_request | General validation error |
missing_required_field | Required field is missing |
invalid_field_value | Field value is invalid |
invalid_language_code | Language code not recognized |
invalid_mode | Session mode is invalid |
invalid_provider | Provider configuration is invalid |
not_found_error
Resource doesn’t exist.| Code | Description |
|---|---|
session_not_found | Session ID doesn’t exist |
recording_not_found | Recording ID doesn’t exist |
analysis_not_found | Analysis ID doesn’t exist |
transcript_not_found | Transcript not available |
webhook_endpoint_not_found | Webhook endpoint doesn’t exist |
invalid_request_error
Request is invalid for the current state.| Code | Description |
|---|---|
session_already_ended | Session has already ended |
session_not_active | Session is not in active state |
recording_not_ready | Recording is still processing |
analysis_not_complete | Analysis is still processing |
idempotency_key_in_use | Idempotency key already used with different parameters |
rate_limit_error
Rate limit exceeded.| Code | Description |
|---|---|
rate_limit_exceeded | Too many requests |
concurrent_session_limit | Too many concurrent sessions |
processing_error
Server-side processing failed.| Code | Description |
|---|---|
transcription_failed | Transcription processing failed |
translation_failed | Translation processing failed |
recording_failed | Recording generation failed |
analysis_failed | Analysis processing failed |
provider_error
Telephony provider error.| Code | Description |
|---|---|
provider_connection_failed | Failed to connect to provider |
provider_call_failed | Call failed |
provider_timeout | Provider request timed out |
server_error
Internal server error.| Code | Description |
|---|---|
internal_error | Unexpected server error |
service_unavailable | Service temporarily unavailable |
upstream_error | Upstream service failure |
Handling Errors
JavaScript/Node.js
Python
Retry Logic
Some errors are transient and can be retried:| Error Type | Retry? | Strategy |
|---|---|---|
rate_limit_error | Yes | Use Retry-After header |
server_error | Yes | Exponential backoff |
provider_error | Maybe | Depends on error code |
validation_error | No | Fix the request |
authentication_error | No | Check credentials |
Exponential Backoff
WebSocket Error Codes
WebSocket connections use these close codes:| Code | Reason | Description |
|---|---|---|
1000 | Normal | Clean close |
1008 | Policy Violation | Authentication failed |
1011 | Internal Error | Server error |
4000 | Session Ended | Session was ended |
4001 | Token Expired | Session token expired |
4002 | Rate Limited | Too many messages |
4003 | Invalid Message | Malformed message |
Common Issues
invalid_api_key
invalid_api_key
Cause: API key is incorrect, expired, or revoked.Solution:
- Check the key starts with
sk_live_orsk_test_ - Verify the key in your Developer Portal
- Create a new key if needed
invalid_language_code
invalid_language_code
Cause: Language code not recognized.Solution:
- Use ISO 639-1 codes (e.g.,
de,en,fr) - Check Supported Languages
- For regional variants, use format like
de-CH
session_not_found
session_not_found
Cause: Session ID doesn’t exist or has expired.Solution:
- Verify the session ID format (
sess_xxx) - Check if session has ended
- Sessions expire 24 hours after ending
rate_limit_exceeded
rate_limit_exceeded
Cause: Too many API requests.Solution:
- Check
Retry-Afterheader - Implement exponential backoff
- Consider upgrading your plan