Skip to Content
CallMitraDocs
Errors

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"
  }
}
FieldMeaning
error.typeThe broad category (table below). Use it for generic handling.
error.codeA specific, stable code such as campaign_not_running. Branch on this. Codes are never renamed once published.
error.messageA human-readable explanation. Show or log it, but do not parse it; the wording can change.
error.paramThe request field that caused the error, when there is one (for example phone). Otherwise null.
error.docUrlLink to this code's page in these docs.
error.requestIdThe request's ID, also sent as the X-Request-ID header. Quote it when you contact support (Request IDs).
detailThe 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

TypeTypical statusWhat to do
invalid_request_error400, 405, 413, 422Fix the request. Retrying it unchanged fails the same way.
authentication_error401Check the X-API-Key (or Authorization: Bearer) header; the key may be wrong, revoked or expired.
billing_error402Top up or change the plan in the console.
permission_error403The key or its user may not do this. Check the key's access and resources.
not_found_error404The ID does not exist or belongs to another workspace.
conflict_error409The resource is in a state that does not allow this. Fetch it again, then decide.
idempotency_error409An Idempotency-Key was reused with a different body, or the first request is still running (Idempotency).
rate_limit_error429Wait for Retry-After seconds, then retry (Rate limits).
api_error500, 503Something 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, then error.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, 409 idempotency_request_in_progress (with the same Idempotency-Key), and network timeouts. Use exponential backoff with jitter. For POST requests, send an Idempotency-Key where the endpoint supports it so a retry cannot act twice.
  • Do not retry 4xx errors other than 429 without changing the request.
  • Honour Retry-After when a response carries it.
  • Log requestId with 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.

StatusCodeWhen
400campaign_has_no_agentThe campaign has no agent. Set agentId on the campaign.
400dial_rejectedThe carrier refused the call before it rang. The failed call is in detail.call.id.
400bad_requestAny other refusal. Read the message.
402payment_requiredThe workspace is out of balance or has no plan.
404campaign_not_foundNo such campaign in your workspace.
404lead_not_foundNo such lead in your workspace.
404lead_not_on_campaignThe lead is not an active member of the campaign.
404phone_number_not_foundcreateCall: the phone number is not connected to your workspace.
409campaign_not_runningThe campaign is stopped. Start it, then retry. Resuming a stopped campaign returns it too.
409number_on_dncThe number is on your do-not-call list.
409lead_call_in_progressA call to this lead is still ringing or connected.
409campaign_call_limit_reachedThe campaign is running as many calls as it allows. activeCallId names the call in progress.
409campaign_dial_busyAnother call for this campaign is being placed at this moment.
409carrier_capacity_reachedThe calling number or carrier account is at its call limit. Nothing was charged.
409campaign_no_eligible_leadsNo lead on the campaign can be called now.
422lead_has_no_campaigncallLeadNow: the lead is on no outbound campaign.
422invalid_phone_numbercreateCall: the number to call is not valid.
429concurrent_call_limit_reachedYour plan's simultaneous call limit is in use.
429campaign_daily_cap_reachedThe campaign reached its daily call limit.
502dial_failedThe 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:

CodeStatusTypeMeaning
agent_test_call_failed400invalid_request_errorThe test call could not be placed.
bad_request400invalid_request_errorThe request could not be processed.
campaign_has_no_agent400invalid_request_errorCampaign has no agent assigned.
dial_rejected400invalid_request_errorThe carrier rejected the call.
webhook_event_type_unknown400invalid_request_errorOne or more event types are not recognised.
webhook_https_required400invalid_request_errorThe webhook URL must use https.
webhook_url_invalid400invalid_request_errorThe webhook URL is not a valid public URL.
workspace_required400invalid_request_errorMerchant workspace required
api_key_expired401authentication_errorThe API key has expired.
invalid_api_key401authentication_errorThe API key is invalid or has been revoked.
unauthenticated401authentication_errorAuthentication required.
payment_required402billing_errorYour account does not have enough balance or an active plan for this request.
api_key_route_forbidden403permission_errorThis endpoint cannot be called with an API key.
api_key_scope_denied403permission_errorThe API key does not have the scope required for this request.
permission_denied403permission_errorYou do not have permission to perform this action.
ticket_edit_forbidden403permission_errorYou can only update tickets assigned to you or unassigned.
ticket_reopen_forbidden403permission_errorOnly a manager can reopen a closed ticket.
webhook_workspace_required403permission_errorWebhooks are managed inside a workspace.
agent_not_found404not_found_errorAgent not found.
call_not_found404not_found_errorCall not found.
call_recording_not_found404not_found_errorNo recording is available for this call.
campaign_not_found404not_found_errorCampaign not found.
lead_not_found404not_found_errorLead not found.
lead_not_on_campaign404not_found_errorLead is not on this campaign.
lead_note_not_found404not_found_errorNote not found.
phone_number_not_found404not_found_errorPhone number not found.
resource_not_found404not_found_errorThe requested resource was not found.
sip_trunk_not_found404not_found_errorSIP trunk not found.
tool_not_found404not_found_errorTool not found.
webhook_delivery_not_found404not_found_errorWebhook delivery not found.
webhook_endpoint_not_found404not_found_errorWebhook endpoint not found.
whatsapp_template_not_found404not_found_errorTemplate not found.
method_not_allowed405invalid_request_errorThis HTTP method is not allowed on this endpoint.
api_key_limit_reached409conflict_errorThis workspace already has the maximum number of active API keys.
campaign_call_limit_reached409conflict_errorCampaign already has an active call in progress.
campaign_default_inbound_exists409conflict_errorAnother default inbound campaign already exists for this phone number.
campaign_dial_busy409conflict_errorCampaign dial in progress.
campaign_leads_need_confirmation409conflict_errorSome leads were already contacted in this campaign.
campaign_no_eligible_leads409conflict_errorNo leads available for calling.
campaign_not_running409conflict_errorCampaign is not active.
carrier_capacity_reached409conflict_errorThe phone number or carrier account is at its call limit.
conflict409conflict_errorThe request conflicts with the current state of the resource.
idempotency_key_reused409idempotency_errorThis Idempotency-Key was already used with a different request body.
idempotency_request_in_progress409idempotency_errorA request with this Idempotency-Key is still being processed.
lead_call_in_progress409conflict_errorLead already has an active call.
lead_changed409conflict_errorThis lead changed since you opened it.
lead_note_changed409conflict_errorThis note was changed by someone else.
lead_note_pin_limit409conflict_errorA lead can have at most 3 pinned notes.
number_on_dnc409conflict_errorThis number is on the DNC list and will not be dialed.
ticket_attachment_unavailable409conflict_errorAn attachment was already sent or removed.
ticket_merged409conflict_errorThe ticket was merged into another ticket.
ticket_reply_blocked409conflict_errorThe reply cannot be sent to the customer.
ticket_version_conflict409conflict_errorThe ticket was changed since you read it.
webhook_endpoint_disabled409conflict_errorThe webhook endpoint is disabled.
webhook_endpoint_limit_reached409conflict_errorThis workspace already has the maximum number of webhook endpoints.
whatsapp_client_message_id_reused409conflict_errorThis message id was already used for a different conversation.
whatsapp_marketing_opted_out409conflict_errorThe recipient stopped marketing messages.
whatsapp_number_not_connected409conflict_errorNo connected WhatsApp number.
whatsapp_opt_in_required409conflict_errorMarketing templates need a recorded opt-in.
whatsapp_recipient_opted_out409conflict_errorThe recipient opted out of WhatsApp messages.
whatsapp_template_not_approved409conflict_errorThe template is not approved.
whatsapp_window_closed409conflict_errorThe 24-hour customer service window is closed.
call_recording_deleted410not_found_errorThis recording was deleted under the data retention policy.
payload_too_large413invalid_request_errorThe request body is too large.
agent_state_blocked422invalid_request_errorThe agent cannot make this change yet.
campaign_not_ready422invalid_request_errorThe campaign is not ready to start.
destination_not_allowed422invalid_request_errorCalls to this country are not enabled for your workspace.
dnc_no_valid_numbers422invalid_request_errorAdd at least one Indian mobile number.
invalid_phone_number422invalid_request_errorThe phone number is not valid.
lead_has_no_campaign422invalid_request_errorLead is not on a campaign.
parameter_invalid422invalid_request_errorOne or more parameters are invalid.
phone_number_not_dialable422invalid_request_errorThis phone number cannot place calls.
campaign_daily_cap_reached429rate_limit_errorDaily call limit reached for this campaign.
concurrent_call_limit_reached429rate_limit_errorMerchant concurrent call limit reached.
daily_call_limit_reached429rate_limit_errorYour workspace reached its daily limit for calls placed through the API.
rate_limit_exceeded429rate_limit_errorToo many requests. Slow down and retry later.
whatsapp_upstream_throttled429rate_limit_errorWhatsApp is limiting messages from this number right now.
internal_error500api_errorSomething went wrong on our side.
dial_failed502api_errorFailed to place outbound call.
service_unavailable503api_errorThe service is temporarily unavailable.
whatsapp_upstream_unavailable503api_errorWhatsApp could not take the message right now.

On this page