Update the assistant settings
curl --fail-with-body -X PATCH 'https://api.talki.it/v1/account' \ -H "Authorization: Bearer $TALKI_API_KEY" \ -H "Idempotency-Key: assistant-settings-2026-10" \ -H "Content-Type: application/json" \ --data '{"instructions":"Always use the formal register. Never quote prices for colour treatments.","voice":"Sulafat","greeting":"Come posso aiutarla?","transfer_numbers":[{"label":"Reception","phone":"+390351234567"}]}'from talki import Talki
talki = Talki()
account = talki.account.update( body={ "instructions": "Always use the formal register. Never quote prices for colour treatments.", "voice": "Sulafat", "greeting": "Come posso aiutarla?", "transfer_numbers": [{"label": "Reception", "phone": "+390351234567"}], }, idempotency_key="assistant-settings-2026-10",)print(account)import { Talki } from "@hubtec/talki";
const talki = new Talki();
const account = await talki.account.update({ body: { instructions: "Always use the formal register. Never quote prices for colour treatments.", voice: "Sulafat", greeting: "Come posso aiutarla?", transfer_numbers: [{ label: "Reception", phone: "+390351234567" }], }, idempotencyKey: "assistant-settings-2026-10",});console.log(account);Change any of the account’s writable fields: the assistant’s settings, the transfer numbers or the forwarding number. Omitted fields stay unchanged; a body with none of them is refused. A custom call_opening needs a plan that includes it, and store_transcripts: false is refused with a test-mode credential. Send If-Match with the ETag of your last read to be refused rather than overwrite a change made since. Requires account:write. Limited to 120 requests per minute per account (API key) or per installation (OAuth).
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters”Header Parameters
Section titled “Header Parameters”Example
2026-10-01Serve this one request at the given dated contract version instead of the credential’s pin. An unsupported value is refused with 400 unsupported_version, never downgraded.
Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked Idempotency-Replayed: true, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a 400 asking for a different request (invalid_parameter, invalid_cursor, export_too_large, unknown_scenario, no_services_requested, stay_too_short, stay_too_long, stay_dates_invalid), a 415, a 409 request_conflict, document_not_ready or check_in_progress, a 412, a 429 and a 5xx.
Example
assistant-settings-2026-10The ETag of your last read. If the stored version is a different one, the write is refused with 412 precondition_failed, unless it asks for exactly what is already stored, so retrying a write that succeeded is safe. * always matches; a weak tag (W/…) never does. Without it, the write replaces whatever is stored.
Example
"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"Request Bodyrequired
Section titled “Request Bodyrequired”The settings you can change. Every field is optional and an omitted one is left unchanged, but send at least one. A null or empty text clears it; a voice, a switch or the transfer list cannot be null. With ?location_id=, the settings change at that location only. call_auto_archive_days is the account’s: it is refused with a location_id other than the main location’s.
object
A voice id from GET /v1/voices. Cannot be null.
business or owner. Cannot be null.
Cannot be null.
The whole list, replacing every existing entry. Send an empty list to remove them all; null is refused. A non-empty list needs the main location’s forwarding_number, already stored or sent in the same request, and may not contain it, nor the location’s own forwarding_number: a call transferred there would come straight back to the assistant.
A transfer target to store; the number is stored as E.164.
object
Who answers at this number, such as “Reception”. Unique within the list, ignoring case: the assistant picks a target by its label.
The number. E.164, or a national number, which is read in the country of the account’s phone_number. Stored as E.164. A premium-rate or shared-cost number is refused, unless the list being replaced already holds it.
Cannot be null.
Cannot be null.
Cannot be null.
Cannot be null.
Cannot be null.
Cannot be null. false deletes the stored transcripts of this location’s calls in the same request, and they cannot be recovered, so a test-mode credential sending it is refused with livemode_required.
Example
{ "instructions": "Always use the formal register. Never quote prices for colour treatments.", "voice": "Sulafat", "greeting": "Come posso aiutarla?", "transfer_numbers": [ { "label": "Reception", "phone": "+390351234567" } ]}Responses
Section titled “ Responses ”Successful Response
The account a credential belongs to, and everything its owner sets up for the assistant: the business name and texts, the voice, the opening and greeting, the switches, the transfer numbers, and the line that forwards to Talki. GET /v1/account needs only account:read, which makes it the call to validate a new credential. The settings are those of one location: the main one, or the one ?location_id= names, the switches included. Only the account’s own fields (id, timezone, livemode, test, multi_sede, onboarding_completed and call_auto_archive_days) read the same at every location. The response’s ETag covers every writable field at that location; send it back as If-Match on PATCH /v1/account with the same location_id. account.updated reports a change to the main location’s settings or to call_auto_archive_days, location.settings_updated one to another location’s settings, its switches included.
object
Opaque Talki account identifier.
The location these settings are of, an id from GET /v1/locations: the one the request named with location_id, or the main location when it named none.
IANA timezone all naive local times for this account resolve against.
False when this credential does not act on real data: a test-mode key (talki_test_…), or an app installed on a developer sandbox or on a test account. Webhook envelopes carry the same flag.
True for a test account your app created with "test": true on POST /oauth/managed-accounts. It has no Talki number, nobody is billed for it or emailed, and it is erased seven days after it was created. Its livemode is false.
The voice the assistant speaks with on calls. One of the ids listed by GET /v1/voices.
Which name the assistant answers calls in and speaks for: business uses business_name, owner uses the account holder’s own name. If the chosen name is empty, the other one is used.
True when the assistant may switch to English, French, German or Spanish to follow the caller. False keeps every call in Italian. The opening is always in Italian.
The languages calls may be held in, derived from multilingual_enabled. Read only.
object
The language every call opens in, before the caller has said anything. Always it today.
Every language the assistant may speak, primary first: it alone while multilingual_enabled is false, otherwise it, en, fr, de and es. More may be added. Read only: change it through multilingual_enabled.
People or lines the assistant may hand a call over to. Empty when the assistant never transfers calls.
A person or line the assistant may hand a call over to.
object
Who answers at this number, such as “Reception” or “Dr. Bianchi”. The assistant uses it to pick the right target for a caller, and call.transferred reports it as target_label.
The number, E.164.
True when the assistant books, moves and cancels appointments on calls. False makes it answer questions and take messages only. Does not affect the appointment endpoints of this API.
True when the assistant offers to record a question it cannot answer, so the business can follow up. Recorded questions are listed by GET /v1/unresolved_requests.
True when the assistant recognises returning callers from the contact book and keeps notes about them for their next call. False treats every call as a first call and keeps nothing about the caller after it ends.
True when the owner gets a push notification on the Talki mobile app after each call, with its summary. Push only, and only on phones where the owner is signed in to the app with notifications allowed; bookings, conflicts and unresolved questions push whatever this says. Talki sends no email or SMS per call: build those on the call.ended and appointment.created events.
True when the owner gets a push notification on the Talki mobile app while a call is ringing, naming the caller, for every caller. Callers marked VIP push whatever this says. Push only, as for notify_on_every_call.
True when the words of each call to this location are kept, readable through GET /v1/calls/{id}/transcript. Setting it to false deletes the transcripts already stored for this location’s calls; call records and summaries are kept.
The location’s Talki number, its line that forwards to it, and whether that forwarding has been proven. Read only. The same as Location.line.
object
no_number while the account has no Talki number. unverified until a forwarding check of the current forwarding_number has succeeded, including while no forwarding_number is set. verified once one has. It proves forwarding was on at verified_at, not that it still is: the business can switch it off at its carrier without Talki knowing. Changing forwarding_number returns it to unverified. A check that finds no forwarding does not change it; read that outcome from GET /v1/forwarding_check.
True when the account works from several locations, or may add them: show locations (GET /v1/locations) to the owner only when true. False for an account that has only ever had its main location and cannot add another; it still has that one location, every record still carries its location_id, and nothing changes shape when this turns true. Read only.
True once the account has finished setting up its assistant. While false, the Talki app opens its setup wizard. Set it with POST /v1/account/complete_onboarding; it never goes back to false.
Example
{ "id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286", "location_id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40", "business_name": "Studio Bellini", "timezone": "Europe/Rome", "livemode": true, "test": false, "business_information": "Free parking in the courtyard behind the salon. We do not sell gift cards.", "instructions": "Always use the formal register. Never quote prices for colour treatments.", "voice": "Sulafat", "answers_as": "business", "call_auto_archive_days": null, "greeting": "Come posso aiutarla?", "call_opening": null, "multilingual_enabled": true, "languages": { "primary": "it", "supported": [ "it", "en", "fr", "de", "es" ] }, "service_area": "Bergamo e provincia", "transfer_numbers": [ { "label": "Reception", "phone": "+390351234567" } ], "bookings_enabled": true, "unresolved_requests_enabled": true, "remember_callers": true, "store_transcripts": true, "notify_on_every_call": true, "notify_on_incoming_call": false, "phone_number": "+390350000001", "forwarding_number": "+393331112222", "line": { "phone_number": "+390350000001", "forwarding_number": "+393331112222", "status": "verified", "verified_at": "2026-10-07T09:30:12Z" }, "multi_sede": true, "onboarding_completed": true}Headers
Section titled “Headers”Identifier to include when contacting Talki support.
Example
2026-10-01The dated contract version this response was served at.
Example
"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"Strong entity tag of the writable content. Send it as If-Match on the next write. Absent on a response replayed from an Idempotency-Key; read again for a current one.
true when this response was replayed from a prior request with the same key.
No writable field was sent, or a value is invalid (invalid_parameter). That includes a forwarding_number equal to a transfer target of any location or to another location’s line, a non-empty transfer_numbers while the main location has no forwarding_number stored or sent, a transfer target equal to a location’s line, and clearing the main location’s forwarding_number while any location has transfer_numbers; this location’s may be replaced in the same request. Talki-Version may also name an unsupported version (unsupported_version).
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "invalid_request", "code": "invalid_parameter", "message": "`forwarding_number` is one of the `transfer_numbers`: a call transferred there would come straight back to the assistant. Remove it from `transfer_numbers` first, or in the same request.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The credential is missing, malformed, expired, revoked, or unknown.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "authentication_error", "code": "invalid_credentials", "message": "The supplied API credential is invalid.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account does not have an active subscription.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "permission_error", "code": "subscription_inactive", "message": "This account does not have an active subscription.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
This account’s plan does not include a custom call_opening (plan_feature_unavailable), or the credential lacks the scope (insufficient_scope).
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "permission_error", "code": "plan_feature_unavailable", "message": "This account's plan does not include a custom `call_opening`. Clearing it is allowed on every plan.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
location_id names no location of the authenticated account.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "invalid_request", "code": "resource_not_found", "message": "No such location.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
store_transcripts: false was sent with a test-mode credential (livemode_required), or the idempotency key was reused for a different request. Except idempotency_key_reuse, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "conflict", "code": "livemode_required", "message": "`store_transcripts: false` deletes the account's stored transcripts for good, so it is not available in test mode.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
If-Match names a version other than the stored one: the settings changed since you read them. Read them again, reapply your change, and retry with the new ETag.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "conflict", "code": "precondition_failed", "message": "This resource changed after the version named in If-Match. Fetch it again, reapply your change, and retry with the new ETag.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account or installation exceeded its request rate (rate_limit_exceeded), or the calling address did (ip_rate_limited).
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the interval in Retry-After.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
Seconds to wait before retrying.
The budget of the window that was exceeded. Absent on ip_rate_limited.
Requests left in the window. Absent on ip_rate_limited.
When the window resets, in Unix seconds. Absent on ip_rate_limited.
An unexpected error occurred.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected error occurred. Quote the request_id when reporting it.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.