API errors - Tars Docs

Failures use application/problem+json with the same shape across API resources.

Problem object

Field	Meaning
title	Human-readable summary
status	HTTP status code
detail	Explanation for this request
instance	req_ request ID for logs and support
code	Stable machine-readable code
retryable	Whether retrying can succeed

Some codes add extensions such as required, region, errors, field, contactId, callId or reason. Validation errors contain entries with path, code and optional message. Branch on code rather than matching title or detail text.

Codes

Code	Status	Title	Retryable	Extensions
invalid_json	400	Request body is not valid JSON	false	None
validation_failed	400	Request failed validation	false	errors
variable_key_not_allowed	400	A variable is not allowed	false	errors
invalid_variable_value	400	A variable value is not valid	false	errors
cursor_expired	400	The cursor has expired	false	None
cursor_mismatch	400	The cursor belongs to another request	false	None
campaign_mode_invalid	400	Campaign is not in webhook mode	false	None
unauthorized	401	Missing or invalid authorization	false	None
invalid_key	401	Invalid or revoked API key	false	None
session_invalid	401	The voice widget session is invalid	false	None
insufficient_balance	402	Insufficient credit balance	false	None
organization_inactive	403	Organization is inactive	false	None
billing_locked	403	A paid plan is required	false	None
permission_missing	403	The API key lacks the permission this endpoint requires	false	required
resource_not_allowed	403	The API key cannot reach this resource	false	None
entitlement_missing	403	Voice is unavailable for this organization	false	callId, reason
origin_not_allowed	403	This site may not start calls	false	None
recaptcha_failed	403	reCAPTCHA verification failed	false	None
consent_revoked	403	Recipient has opted out	false	None
us_marketing_blocked	403	US marketing message blocked	false	None
channel_test_mode	403	Channel is in test mode	false	None
quota_exceeded	403	A plan limit has been reached	false	None
forbidden	403	The request is not allowed	false	None
not_found	404	Not found	false	None
method_not_allowed	405	Method not allowed	false	None
wrong_region	409	The organization lives in another region	false	region
conflict	409	The resource changed since you read it	false	None
contact_exists	409	A contact with this email or phone already exists	false	field, contactId
idempotency_key_reuse	409	Idempotency key was used for another request	false	None
agent_unavailable	409	The agent is not available	false	callId, reason
call_not_live	409	The call is not live	false	None
call_still_live	409	The call is still live	false	None
call_content_deleted	409	The call content has been deleted	false	None
invalid_state	409	The resource does not allow this change now	false	callId, reason
campaign_paused	409	Campaign is not active	true	None
template_version_drift	409	Template version drift	false	None
channel_unavailable	409	Channel account is unavailable	true	None
artefact_deleted	410	The artefact has been deleted	false	None
campaign_gone	410	Campaign has ended	false	None
payload_too_large	413	Request body is too large	false	None
template_not_approved	422	Template is not approved	false	None
channel_misconfigured	422	Channel is misconfigured	false	None
channel_reauth_required	422	WhatsApp connection expired : reconnect the account	false	None
meta_rejected	422	Message rejected by WhatsApp	false	None
rate_limited	429	Rate limit exceeded	true	callId, reason
concurrency_limit_reached	429	No call slot is free	true	callId, reason
worker_busy	429	All agents are busy right now	true	callId, reason
meta_rate_limited	429	WhatsApp is rate limiting sends	true	None
internal_error	500	Internal error	false	None
upstream_unavailable	503	A provider Tars depends on is unavailable	true	None
meta_unavailable	503	WhatsApp is temporarily unavailable	true	None
worker_not_deployed	503	No voice worker serves this deployment	false	callId, reason
worker_unavailable	503	No voice worker is available right now	true	callId, reason

Retrying

Retry only when retryable is true. Every retryable problem carries Retry-After in seconds. Wait at least that long before trying again. For call creation, preserve Idempotency-Key when retrying the same request. See Requests.

Request IDs

Keep instance with your logs. Include it when asking support about a failure. Do not log API keys or secret request headers.