Коды ошибок и пример от начала до конца
Коды ошибок
По типам
| Статус | error.type | Коды на эндпоинтах этого справочника |
|---|---|---|
| 400 | invalid_request_error | caller_number_not_allowed, caller_number_outside_grant_pool, destination_number_invalid, ring_duration_invalid, invalid_filter_value, invalid_cursor |
| 401 | authentication_error | api_key_required, api_key_unknown, api_key_revoked |
| 403 | permission_error | agent_not_in_subgroup, destination_not_allowed, privileged_key_required, root_org_key_required |
| 404 | not_found_error | trunk_not_found, subgroup_not_found, call_not_found, campaign_not_found, import_not_found, agent_not_found (только веб-звонки) |
| 409 | conflict_error | agent_subgroup_ambiguous, agent_not_published, launch_blocked, campaign_transition_invalid, campaign_closed, market_package_not_installed, idempotency_key_in_flight, dnc_decision_without_upload, dnc_screen_required |
| 422 | invalid_request_error | invalid_request (схема) и коды кампаний ниже |
| 429 | rate_limit_error | api_key_rate_limit_exceeded, dial_queue_full, subgroup_concurrency_limit, subgroup_rate_limit |
| 500 | api_error | internal_error |
| 502 | api_error | dial_failed (только синхронный запасной режим), contact_file_storage_unavailable |
| 503 | service_unavailable_error | voice_backend_unavailable, agent_dispatch_failed (веб-звонки) |
Коды ошибок кампаний
| Статус | error.code | Причина |
|---|---|---|
| 404 | campaign_not_found / import_not_found | Такого объекта в вашей организации нет; всё, что за её границей, неотличимо от отсутствующего. |
| 409 | launch_blocked | Проверки запуска или возобновления не пройдены; список — в error.blockers. |
| 409 | campaign_transition_invalid | Переход невозможен из текущего состояния. |
| 409 | campaign_closed | calls: кампания завершена или отменена. |
| 409 | market_package_not_installed | Контакты нельзя проверить для этой организации; обратитесь в поддержку. |
| 409 | idempotency_key_in_flight | Запрос с этим ключом ещё обрабатывается; дождитесь ответа. |
| 409 | dnc_decision_without_upload | Решение dnc у кампании, у которой нет загрузки. |
| 409 | dnc_screen_required | У загрузки нет построчной проекции: при решении dnc, при ?only=dnc_match или как блокер запуска. Загрузите заново. |
| 422 | invalid_request | Тело не проходит проверку схемы; message — массив замечаний по полям. |
| 422 | idempotency_key_required | Заголовок Idempotency-Key отсутствует или пуст. |
| 422 | idempotency_key_reuse | Этот ключ уже использован для другого тела запроса. |
| 422 | campaign_agent_unknown | Агента с таким именем в вашей организации нет. |
| 422 | campaign_window_invalid | ends_at не позже starts_at. |
| 422 | campaign_timezone_unknown | Не название зоны IANA. |
| 422 | campaign_classification_invalid | classification не одно из трёх документированных значений. |
| 422 | campaign_spec_invalid | Отклонены длина названия, ступень скорости, настройка повторов, форма рабочих часов или действие по дублям. |
| 422 | campaign_open_ends_at_required / campaign_open_ends_at_too_far | У кампании, открытой к добавлению звонков, нет ends_at или он за горизонтом. |
| 422 | dialing_route_unresolved / dialing_route_ambiguous | Нет привязки или больше одного кандидата. |
| 422 | dialing_binding_incomplete | route_id или from_number названы без trunk_id. |
| 422 | working_hours_wider_than_law | Расписание шире базового окна (законного или окна обзвона организации). |
| 422 | attestation_import_id_required | В launch нет attestation.import_id. |
| 422 | dnc_decision_invalid | dnc не block и не skip. |
| 422 | contact_rows_rejected | Запланированные звонки не удалось сохранить вовсе; читайте отчёт по загрузке. |
| 422 | report_format_invalid | format не csv и не xlsx. |
| 422 | report_filter_invalid | only не опущен и не dnc_match. |
| 422 | calls_required / calls_batch_too_large | calls пуст или содержит больше строк, чем предел (по умолчанию 1000). |
| 422 | attestation_invalid | calls: attestation не равна в точности {"confirmed": true}. |
| 422 | calls_rejected | Партия отклонена целиком из-за ошибки данных (или структурного отказа разбора); строки названы в error.import. |
| 422 | calls_dnc_matched | Партия отклонена целиком, потому что хотя бы один номер есть в реестре «не звонить»; читайте отчёт dnc_match. |
| 502 | contact_file_storage_unavailable | Источник контактов не удалось сохранить, загрузка не принята — повторите. |
Пример от начала до конца
BASE_URL="https://app.hubtalk.kz" # адрес вашего кабинета; Узбекистан — app.hubtalk.uz
API_KEY="cfk_…" # секрет, показанный один раз при создании ключа
# 1. Посмотреть доступные агенту линии (необязательно: не присылайте
# привязку вовсе, и платформа разрешит её сама)
curl -s "$BASE_URL/v1/dialing-routes?agent_id=collections-agent" \
-H "Authorization: Bearer $API_KEY"
# 2. Создать кампанию, передать номера и запустить — один запрос
curl -s -X POST "$BASE_URL/v1/campaigns" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: june-collections-2026-09-09" \
-d '{
"name": "june collections",
"agent_id": "collections-agent",
"calls_per_minute": 10,
"timezone": "Asia/Almaty",
"classification": "debt_collection",
"working_hours": [{"days": [0,1,2,3,4], "start": "09:00", "end": "19:00"}],
"attestation": {"confirmed": true},
"planned_calls": [
{"phone": "+77001234567", "name": "Aigerim", "variables": {"debt": "15000"}},
{"phone": "+77007654321", "name": "Daniyar"}
]
}'
# → 201. Смотрим "status": "running" | "scheduled" | "draft".
# "draft" означает, что причина названа в "blockers": исправить и вызвать
# POST /v1/campaigns/{id}/launch с
# {"attestation": {"confirmed": true, "import_id": "<import.import_id>"}}
# Учтите: по умолчанию retry_config.attempts = 1 — никого не перезванивают.
# 3. Дослать номера позже (кампания не должна быть закрыта)
curl -s -X POST "$BASE_URL/v1/campaigns/cam-b9b536a86e/calls" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: crm-batch-2026-09-09-17" \
-d '{"calls": [{"phone": "+77009998877", "name": "Symbat"}],
"attestation": {"confirmed": true}}'
# → 201 (принята целиком) либо 422 calls_rejected / calls_dnc_matched (отклонена целиком)
# 4. Следить за ходом
curl -s "$BASE_URL/v1/campaigns/cam-b9b536a86e/progress" \
-H "Authorization: Bearer $API_KEY"
# 5. Разобрать проблемные строки
curl -s "$BASE_URL/v1/imports/imp-353d158dd2/report?format=csv" \
-H "Authorization: Bearer $API_KEY" -o import-report.csv
# ...и отдельно совпадения с реестром «не звонить»
curl -s "$BASE_URL/v1/imports/imp-353d158dd2/report?only=dnc_match&format=csv" \
-H "Authorization: Bearer $API_KEY" -o import-dnc.csv
# 6. Результаты по каждому звонку придут вебхуками call_ended / call_analyzed —
# кампания набирает те же самые звонки, что этот API размещает по одному