# Errors (/errors)

Every error response uses an HTTP status code and the same JSON body:

```json
{
  "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](/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 [#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](/idempotency)). |
| `rate_limit_error` | 429 | Wait for `Retry-After` seconds, then retry ([Rate limits](/rate-limits)). |
| `api_error` | 500, 503 | Something went wrong on our side. Retry with backoff. |

## Validation errors [#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:

```json
{
  "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 [#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`](/errors/idempotency_request_in_progress) (with the same `Idempotency-Key`), and network timeouts. Use exponential backoff with jitter. For `POST` requests, send an [`Idempotency-Key`](/idempotency) 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.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -sS https://api.callmitra.ai/api/v1/leads/00000000-0000-0000-0000-000000000000 \
  -H "X-API-Key: $CALLMITRA_API_KEY" | jq '.error'
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } });
if (!res.ok) {
  const { error } = await res.json();
  if (res.status === 429 || res.status >= 500) {
    // retry later with backoff; honour Retry-After when present
  }
  throw new Error(`${error.code}: ${error.message} (request ${error.requestId})`);
}
```
</Tab>

<Tab value="Python">
```python
res = requests.get(url, headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, timeout=30)
if not res.ok:
    error = res.json()["error"]
    if res.status_code == 429 or res.status_code >= 500:
        pass  # retry later with backoff; honour Retry-After when present
    raise RuntimeError(f"{error['code']}: {error['message']} (request {error['requestId']})")
```
</Tab>
</Tabs>

## Calling refusals [#calling-refusals]

[`POST /api/v1/instant/call-now`](/api-reference/calls/callNow), [`POST /api/v1/leads/{lead_id}/call-now`](/api-reference/calls/callLeadNow) and [`POST /api/v1/calls/`](/api-reference/calls/createCall) 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`](/errors/campaign_has_no_agent) | The campaign has no agent. Set `agentId` on the campaign. |
| `400` | [`dial_rejected`](/errors/dial_rejected) | The carrier refused the call before it rang. The failed call is in `detail.call.id`. |
| `400` | [`bad_request`](/errors/bad_request) | Any other refusal. Read the message. |
| `402` | [`payment_required`](/errors/payment_required) | The workspace is out of balance or has no plan. |
| `404` | [`campaign_not_found`](/errors/campaign_not_found) | No such campaign in your workspace. |
| `404` | [`lead_not_found`](/errors/lead_not_found) | No such lead in your workspace. |
| `404` | [`lead_not_on_campaign`](/errors/lead_not_on_campaign) | The lead is not an active member of the campaign. |
| `404` | [`phone_number_not_found`](/errors/phone_number_not_found) | `createCall`: the phone number is not connected to your workspace. |
| `409` | [`campaign_not_running`](/errors/campaign_not_running) | The campaign is stopped. Start it, then retry. Resuming a stopped campaign returns it too. |
| `409` | [`number_on_dnc`](/errors/number_on_dnc) | The number is on your do-not-call list. |
| `409` | [`lead_call_in_progress`](/errors/lead_call_in_progress) | A call to this lead is still ringing or connected. |
| `409` | [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) | The campaign is running as many calls as it allows. `activeCallId` names the call in progress. |
| `409` | [`campaign_dial_busy`](/errors/campaign_dial_busy) | Another call for this campaign is being placed at this moment. |
| `409` | [`carrier_capacity_reached`](/errors/carrier_capacity_reached) | The calling number or carrier account is at its call limit. Nothing was charged. |
| `409` | [`campaign_no_eligible_leads`](/errors/campaign_no_eligible_leads) | No lead on the campaign can be called now. |
| `422` | [`lead_has_no_campaign`](/errors/lead_has_no_campaign) | `callLeadNow`: the lead is on no outbound campaign. |
| `422` | [`invalid_phone_number`](/errors/invalid_phone_number) | `createCall`: the number to call is not valid. |
| `429` | [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) | Your plan's simultaneous call limit is in use. |
| `429` | [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached) | The campaign reached its daily call limit. |
| `502` | [`dial_failed`](/errors/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](/guides/india-calling) for calling windows and do-not-call rules.

## All error codes [#all-error-codes]

Each endpoint in the [API reference](/api-reference) lists the codes it can return under its responses. The full catalogue:

<ErrorCodeTable />