Errors
One error envelope for every endpoint, with a stable code you can branch on.
Every error response uses an HTTP status code and the same JSON body:
{
"detail": "Lead not found",
"error": {
"type": "not_found_error",
"code": "lead_not_found",
"message": "Lead not found",
"param": null,
"docUrl": "https://docs.callmitra.ai/errors/lead_not_found",
"requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69"
}
}| Field | Meaning |
|---|---|
error.type | The broad category (table below). Use it for generic handling. |
error.code | A specific, stable code such as campaign_not_running. Branch on this. Codes are never renamed once published. |
error.message | A human-readable explanation. Show or log it, but do not parse it; the wording can change. |
error.param | The request field that caused the error, when there is one (for example phone). Otherwise null. |
error.docUrl | Link to this code's page in these docs. |
error.requestId | The request's ID, also sent as the X-Request-ID header. Quote it when you contact support (Request IDs). |
detail | The earlier error format, kept for existing integrations: a message string, an object, or for 422 the list of field errors. New code should read error. |
Error types
| Type | Typical status | What to do |
|---|---|---|
invalid_request_error | 400, 405, 413, 422 | Fix the request. Retrying it unchanged fails the same way. |
authentication_error | 401 | Check the X-API-Key (or Authorization: Bearer) header; the key may be wrong, revoked or expired. |
billing_error | 402 | Top up or change the plan in the console. |
permission_error | 403 | The key or its user may not do this. Check the key's access and resources. |
not_found_error | 404 | The ID does not exist or belongs to another workspace. |
conflict_error | 409 | The resource is in a state that does not allow this. Fetch it again, then decide. |
idempotency_error | 409 | An Idempotency-Key was reused with a different body, or the first request is still running (Idempotency). |
rate_limit_error | 429 | Wait for Retry-After seconds, then retry (Rate limits). |
api_error | 500, 503 | Something went wrong on our side. Retry with backoff. |
Validation errors
A 422 means a field is missing or invalid. error.code is parameter_invalid, error.param names the first offending field, and detail lists every problem:
{
"detail": [
{ "type": "missing", "loc": ["body", "phone"], "msg": "Field required" }
],
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "One or more parameters are invalid.",
"param": "phone",
"docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
"requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69"
}
}Handling errors well
- Branch on
error.code, thenerror.type, then the status. Unknown codes can appear as the API grows; fall back to the type. - Retry only what can succeed later:
429,500,503,409idempotency_request_in_progress(with the sameIdempotency-Key), and network timeouts. Use exponential backoff with jitter. ForPOSTrequests, send anIdempotency-Keywhere the endpoint supports it so a retry cannot act twice. - Do not retry
4xxerrors other than429without changing the request. - Honour
Retry-Afterwhen a response carries it. - Log
requestIdwith every failure.
curl -sS https://api.callmitra.ai/api/v1/leads/00000000-0000-0000-0000-000000000000 \
-H "X-API-Key: $CALLMITRA_API_KEY" | jq '.error'Calling refusals
POST /api/v1/instant/call-now, POST /api/v1/leads/{lead_id}/call-now and POST /api/v1/calls/ are refused for business reasons as well as technical ones. Each refusal has its own code. error.message is safe to show to a person, and detail keeps the earlier message format.
| Status | Code | When |
|---|---|---|
400 | campaign_has_no_agent | The campaign has no agent. Set agentId on the campaign. |
400 | dial_rejected | The carrier refused the call before it rang. The failed call is in detail.call.id. |
400 | bad_request | Any other refusal. Read the message. |
402 | payment_required | The workspace is out of balance or has no plan. |
404 | campaign_not_found | No such campaign in your workspace. |
404 | lead_not_found | No such lead in your workspace. |
404 | lead_not_on_campaign | The lead is not an active member of the campaign. |
404 | phone_number_not_found | createCall: the phone number is not connected to your workspace. |
409 | campaign_not_running | The campaign is stopped. Start it, then retry. Resuming a stopped campaign returns it too. |
409 | number_on_dnc | The number is on your do-not-call list. |
409 | lead_call_in_progress | A call to this lead is still ringing or connected. |
409 | campaign_call_limit_reached | The campaign is running as many calls as it allows. activeCallId names the call in progress. |
409 | campaign_dial_busy | Another call for this campaign is being placed at this moment. |
409 | carrier_capacity_reached | The calling number or carrier account is at its call limit. Nothing was charged. |
409 | campaign_no_eligible_leads | No lead on the campaign can be called now. |
422 | lead_has_no_campaign | callLeadNow: the lead is on no outbound campaign. |
422 | invalid_phone_number | createCall: the number to call is not valid. |
429 | concurrent_call_limit_reached | Your plan's simultaneous call limit is in use. |
429 | campaign_daily_cap_reached | The campaign reached its daily call limit. |
502 | dial_failed | The carrier could not be reached. The failed call is in detail.call.id. |
lead_call_in_progress, campaign_call_limit_reached, campaign_dial_busy, carrier_capacity_reached and concurrent_call_limit_reached clear on their own, so retrying after a short wait can succeed. Retry dial_failed with backoff. New codes may be added; handle an unknown code by falling back to error.type. See Calling in India for calling windows and do-not-call rules.
All error codes
Each endpoint in the API reference lists the codes it can return under its responses. The full catalogue:
| Code | Status | Type | Meaning |
|---|---|---|---|
agent_test_call_failed | 400 | invalid_request_error | The test call could not be placed. |
bad_request | 400 | invalid_request_error | The request could not be processed. |
campaign_has_no_agent | 400 | invalid_request_error | Campaign has no agent assigned. |
dial_rejected | 400 | invalid_request_error | The carrier rejected the call. |
webhook_event_type_unknown | 400 | invalid_request_error | One or more event types are not recognised. |
webhook_https_required | 400 | invalid_request_error | The webhook URL must use https. |
webhook_url_invalid | 400 | invalid_request_error | The webhook URL is not a valid public URL. |
workspace_required | 400 | invalid_request_error | Merchant workspace required |
api_key_expired | 401 | authentication_error | The API key has expired. |
invalid_api_key | 401 | authentication_error | The API key is invalid or has been revoked. |
unauthenticated | 401 | authentication_error | Authentication required. |
payment_required | 402 | billing_error | Your account does not have enough balance or an active plan for this request. |
api_key_route_forbidden | 403 | permission_error | This endpoint cannot be called with an API key. |
api_key_scope_denied | 403 | permission_error | The API key does not have the scope required for this request. |
permission_denied | 403 | permission_error | You do not have permission to perform this action. |
ticket_edit_forbidden | 403 | permission_error | You can only update tickets assigned to you or unassigned. |
ticket_reopen_forbidden | 403 | permission_error | Only a manager can reopen a closed ticket. |
webhook_workspace_required | 403 | permission_error | Webhooks are managed inside a workspace. |
agent_not_found | 404 | not_found_error | Agent not found. |
call_not_found | 404 | not_found_error | Call not found. |
call_recording_not_found | 404 | not_found_error | No recording is available for this call. |
campaign_not_found | 404 | not_found_error | Campaign not found. |
lead_not_found | 404 | not_found_error | Lead not found. |
lead_not_on_campaign | 404 | not_found_error | Lead is not on this campaign. |
lead_note_not_found | 404 | not_found_error | Note not found. |
phone_number_not_found | 404 | not_found_error | Phone number not found. |
resource_not_found | 404 | not_found_error | The requested resource was not found. |
sip_trunk_not_found | 404 | not_found_error | SIP trunk not found. |
tool_not_found | 404 | not_found_error | Tool not found. |
webhook_delivery_not_found | 404 | not_found_error | Webhook delivery not found. |
webhook_endpoint_not_found | 404 | not_found_error | Webhook endpoint not found. |
whatsapp_template_not_found | 404 | not_found_error | Template not found. |
method_not_allowed | 405 | invalid_request_error | This HTTP method is not allowed on this endpoint. |
api_key_limit_reached | 409 | conflict_error | This workspace already has the maximum number of active API keys. |
campaign_call_limit_reached | 409 | conflict_error | Campaign already has an active call in progress. |
campaign_default_inbound_exists | 409 | conflict_error | Another default inbound campaign already exists for this phone number. |
campaign_dial_busy | 409 | conflict_error | Campaign dial in progress. |
campaign_leads_need_confirmation | 409 | conflict_error | Some leads were already contacted in this campaign. |
campaign_no_eligible_leads | 409 | conflict_error | No leads available for calling. |
campaign_not_running | 409 | conflict_error | Campaign is not active. |
carrier_capacity_reached | 409 | conflict_error | The phone number or carrier account is at its call limit. |
conflict | 409 | conflict_error | The request conflicts with the current state of the resource. |
idempotency_key_reused | 409 | idempotency_error | This Idempotency-Key was already used with a different request body. |
idempotency_request_in_progress | 409 | idempotency_error | A request with this Idempotency-Key is still being processed. |
lead_call_in_progress | 409 | conflict_error | Lead already has an active call. |
lead_changed | 409 | conflict_error | This lead changed since you opened it. |
lead_note_changed | 409 | conflict_error | This note was changed by someone else. |
lead_note_pin_limit | 409 | conflict_error | A lead can have at most 3 pinned notes. |
number_on_dnc | 409 | conflict_error | This number is on the DNC list and will not be dialed. |
ticket_attachment_unavailable | 409 | conflict_error | An attachment was already sent or removed. |
ticket_merged | 409 | conflict_error | The ticket was merged into another ticket. |
ticket_reply_blocked | 409 | conflict_error | The reply cannot be sent to the customer. |
ticket_version_conflict | 409 | conflict_error | The ticket was changed since you read it. |
webhook_endpoint_disabled | 409 | conflict_error | The webhook endpoint is disabled. |
webhook_endpoint_limit_reached | 409 | conflict_error | This workspace already has the maximum number of webhook endpoints. |
whatsapp_client_message_id_reused | 409 | conflict_error | This message id was already used for a different conversation. |
whatsapp_marketing_opted_out | 409 | conflict_error | The recipient stopped marketing messages. |
whatsapp_number_not_connected | 409 | conflict_error | No connected WhatsApp number. |
whatsapp_opt_in_required | 409 | conflict_error | Marketing templates need a recorded opt-in. |
whatsapp_recipient_opted_out | 409 | conflict_error | The recipient opted out of WhatsApp messages. |
whatsapp_template_not_approved | 409 | conflict_error | The template is not approved. |
whatsapp_window_closed | 409 | conflict_error | The 24-hour customer service window is closed. |
call_recording_deleted | 410 | not_found_error | This recording was deleted under the data retention policy. |
payload_too_large | 413 | invalid_request_error | The request body is too large. |
agent_state_blocked | 422 | invalid_request_error | The agent cannot make this change yet. |
campaign_not_ready | 422 | invalid_request_error | The campaign is not ready to start. |
destination_not_allowed | 422 | invalid_request_error | Calls to this country are not enabled for your workspace. |
dnc_no_valid_numbers | 422 | invalid_request_error | Add at least one Indian mobile number. |
invalid_phone_number | 422 | invalid_request_error | The phone number is not valid. |
lead_has_no_campaign | 422 | invalid_request_error | Lead is not on a campaign. |
parameter_invalid | 422 | invalid_request_error | One or more parameters are invalid. |
phone_number_not_dialable | 422 | invalid_request_error | This phone number cannot place calls. |
campaign_daily_cap_reached | 429 | rate_limit_error | Daily call limit reached for this campaign. |
concurrent_call_limit_reached | 429 | rate_limit_error | Merchant concurrent call limit reached. |
daily_call_limit_reached | 429 | rate_limit_error | Your workspace reached its daily limit for calls placed through the API. |
rate_limit_exceeded | 429 | rate_limit_error | Too many requests. Slow down and retry later. |
whatsapp_upstream_throttled | 429 | rate_limit_error | WhatsApp is limiting messages from this number right now. |
internal_error | 500 | api_error | Something went wrong on our side. |
dial_failed | 502 | api_error | Failed to place outbound call. |
service_unavailable | 503 | api_error | The service is temporarily unavailable. |
whatsapp_upstream_unavailable | 503 | api_error | WhatsApp could not take the message right now. |