# Create an agent (/api-reference/agents/createAgent)

## POST /api/v1/agents/

Operation ID: `createAgent`
Create an agent
Creates an agent from a `config` (see the AgentConfig schema). It starts as a `draft`; publish it with publishAgent, or send `status: published`. Values outside the documented range or list, and a language, voice or model that is not available, are refused with `parameter_invalid` naming the field (for example `config.voice`).

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. |

### Request body

`application/json` (required)

```json
{
  "description": "A new agent. It starts as a draft unless `status` is `published`.",
  "properties": {
    "config": {
      "additionalProperties": true,
      "description": "Agent configuration. Omitted keys keep their current (or default) value.\n\nKeys are snake_case by design: this object is the stored agent config and the\nshape importAgent produces, so it is saved and returned exactly as written here,\nwhile the rest of the API uses camelCase. A known key with a bad value is refused\nwith `parameter_invalid` and a `param` path such as `config.tts_volume`. Unknown keys\nare not refused: they are dropped without an error and do not appear in the saved config.",
      "properties": {
        "agent_gender": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Voice gender: `female`, `male` or `any`.",
          "title": "Agent Gender"
        },
        "agent_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Kind of call the agent runs.",
          "enum": [
            "announcement",
            "awareness",
            "conversation",
            "ivr_survey",
            "survey"
          ],
          "title": "Agent Mode"
        },
        "ai_disclosure": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "Tell the caller they are speaking to an AI agent.",
          "title": "Ai Disclosure"
        },
        "auto_adapt_language": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "Follow the caller when they switch language.",
          "title": "Auto Adapt Language"
        },
        "background_sound": {
          "anyOf": [
            {
              "additionalProperties": true,
              "description": "Room tone mixed quietly under the agent's voice.",
              "properties": {
                "enabled": {
                  "anyOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Play the background sound on calls.",
                  "title": "Enabled"
                },
                "preset": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Background sound slug from `GET /background-sounds`, or `off`.",
                  "title": "Preset"
                },
                "volume": {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Loudness of the background sound.",
                  "maximum": 1,
                  "minimum": 0.02,
                  "title": "Volume"
                }
              },
              "title": "AgentBackgroundSound",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Background room tone."
        },
        "call_recording": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "Record calls.",
          "title": "Call Recording"
        },
        "call_time_limit_seconds": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Hard limit on call length.",
          "maximum": 3600,
          "minimum": 10,
          "title": "Call Time Limit Seconds"
        },
        "caller_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Name the agent introduces itself with.",
          "title": "Caller Name"
        },
        "calling_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "`instant` answers new leads right away; `bulk` runs campaigns; empty means not set.",
          "enum": [
            "",
            "bulk",
            "instant"
          ],
          "title": "Calling Mode"
        },
        "conversation_engine": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Turn-taking engine version.",
          "enum": [
            "v1",
            "v2"
          ],
          "title": "Conversation Engine"
        },
        "extra_language": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Second language the agent may switch to, e.g. `hi-IN`.",
          "title": "Extra Language"
        },
        "greeting_message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Shortcut for `template_payload.greeting_message` on write.",
          "title": "Greeting Message"
        },
        "interrupt_min_speech_ms": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Caller speech needed to interrupt (time mode).",
          "maximum": 2000,
          "minimum": 100,
          "title": "Interrupt Min Speech Ms"
        },
        "interrupt_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "How the caller interrupts the agent: by speaking time or by word count.",
          "enum": [
            "time",
            "words"
          ],
          "title": "Interrupt Mode"
        },
        "interrupt_word_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Caller words needed to interrupt (words mode).",
          "maximum": 3,
          "minimum": 1,
          "title": "Interrupt Word Count"
        },
        "interruption_sensitivity": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "How easily the caller can interrupt.",
          "enum": [
            "low",
            "medium",
            "high"
          ],
          "title": "Interruption Sensitivity"
        },
        "job_role": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Job title the agent plays, e.g. `Sales associate`.",
          "title": "Job Role"
        },
        "knowledge": {
          "anyOf": [
            {
              "additionalProperties": true,
              "description": "Facts and answers the agent can use during the call.",
              "properties": {
                "details": {
                  "anyOf": [
                    {
                      "items": {
                        "additionalProperties": true,
                        "type": "object"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Business details as `{key, label, value}` objects.",
                  "title": "Details"
                },
                "items": {
                  "anyOf": [
                    {
                      "items": {
                        "additionalProperties": true,
                        "type": "object"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Knowledge items as `{kind, q, text}`; kind is fact, qa, rule or objection.",
                  "title": "Items"
                },
                "notes": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Free-text notes the agent may use.",
                  "title": "Notes"
                }
              },
              "title": "AgentKnowledgeConfig",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Structured knowledge."
        },
        "language": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Primary call language code from `GET /voices` languages, e.g. `en-IN`, `hi-IN`.",
          "title": "Language"
        },
        "llm_model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Language model id, e.g. `gpt-4o-mini`, `gpt-4.1-mini`.",
          "title": "Llm Model"
        },
        "max_tokens": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Longest reply in tokens.",
          "maximum": 32000,
          "minimum": 1,
          "title": "Max Tokens"
        },
        "noise_reduction": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Background noise filtering.",
          "enum": [
            "off",
            "standard",
            "strong"
          ],
          "title": "Noise Reduction"
        },
        "post_call_webhook": {
          "anyOf": [
            {
              "additionalProperties": true,
              "description": "Where the call summary is sent after each call (read; set it with setAgentPostCallWebhook).",
              "properties": {
                "trigger": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Which calls are sent.",
                  "enum": [
                    "completed",
                    "every",
                    "voicemail"
                  ],
                  "title": "Trigger"
                },
                "url": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "HTTPS endpoint that receives the call summary.",
                  "title": "Url"
                }
              },
              "title": "AgentPostCallWebhookConfig",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Post-call webhook. Prefer setAgentPostCallWebhook, which also stores the signing secret."
        },
        "realtime_model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Realtime speech model when `voice_engine` is not pipeline.",
          "title": "Realtime Model"
        },
        "realtime_voice": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Realtime voice when `voice_engine` is not pipeline.",
          "title": "Realtime Voice"
        },
        "reasoning_effort": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Reasoning effort for models that support it; lower is faster.",
          "enum": [
            "none",
            "minimal",
            "low",
            "medium",
            "high",
            "xhigh",
            "max"
          ],
          "title": "Reasoning Effort"
        },
        "recording_notice": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "Tell the caller the call is recorded.",
          "title": "Recording Notice"
        },
        "required_fields": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "description": "Values to collect on the call, as `{key, label, type}` objects.",
          "title": "Required Fields"
        },
        "script": {
          "anyOf": [
            {
              "additionalProperties": true,
              "description": "Structured call script: opening line, goal, steps and closing.",
              "properties": {
                "ask_first_question_in_greeting": {
                  "anyOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Ask the first step's question in the opening line.",
                  "title": "Ask First Question In Greeting"
                },
                "closing": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Last thing the agent says before hanging up.",
                  "title": "Closing"
                },
                "end_rules": {
                  "anyOf": [
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "When the agent should end the call.",
                  "title": "End Rules"
                },
                "goal": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "What a successful call achieves.",
                  "title": "Goal"
                },
                "opening": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "First thing the agent says when the call connects.",
                  "title": "Opening"
                },
                "steps": {
                  "anyOf": [
                    {
                      "items": {
                        "$ref": "#/components/schemas/AgentScriptStep"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Ordered steps the agent follows.",
                  "title": "Steps"
                },
                "strictness": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "How closely the agent sticks to the steps.",
                  "enum": [
                    "flexible",
                    "balanced",
                    "strict"
                  ],
                  "title": "Strictness"
                }
              },
              "title": "AgentScriptConfig",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Structured call script."
        },
        "stt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Speech-to-text provider id from the active catalog, for example `deepgram` or `sarvam`. An id that is not active is refused with `parameter_invalid`.",
          "title": "Stt"
        },
        "success_criteria": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "What counts as a successful call, for call analysis.",
          "title": "Success Criteria"
        },
        "system_prompt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Shortcut for `template_payload.system_prompt` on write.",
          "title": "System Prompt"
        },
        "temperature": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Sampling temperature.",
          "maximum": 2,
          "minimum": 0,
          "title": "Temperature"
        },
        "template_payload": {
          "anyOf": [
            {
              "additionalProperties": true,
              "description": "Free-form prompt content: system prompt, greeting and knowledge text.",
              "properties": {
                "greeting_message": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Opening line spoken when the call connects.",
                  "title": "Greeting Message"
                },
                "knowledge_base": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Reference text the agent may quote from.",
                  "title": "Knowledge Base"
                },
                "system_prompt": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Instructions for the language model.",
                  "title": "System Prompt"
                }
              },
              "title": "AgentPromptContent",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Free-form prompt content (system prompt, greeting, knowledge text)."
        },
        "tone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Speaking style, e.g. `natural`, `friendly`, `formal`.",
          "title": "Tone"
        },
        "tools": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/components/schemas/AgentToolConfig"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "description": "Tools the agent may use (at most 32).",
          "title": "Tools"
        },
        "tts": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Text-to-speech provider id from `GET /voices` providers.",
          "title": "Tts"
        },
        "tts_speed": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Speaking speed; 1.0 is normal.",
          "maximum": 1.5,
          "minimum": 0.5,
          "title": "Tts Speed"
        },
        "tts_volume": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Voice loudness; 1.0 is full.",
          "maximum": 1,
          "minimum": 0.2,
          "title": "Tts Volume"
        },
        "voice": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Voice id (`voiceId`) from `GET /voices` for the `tts` provider.",
          "title": "Voice"
        },
        "voice_engine": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "`pipeline` uses separate speech-to-text, model and voice; the others use a single realtime speech model.",
          "enum": [
            "pipeline",
            "gemini_live",
            "openai_realtime",
            "elevenlabs_agents"
          ],
          "title": "Voice Engine"
        }
      },
      "title": "AgentConfig",
      "type": "object"
    },
    "name": {
      "default": "",
      "description": "Display name; also the name the agent introduces itself with.",
      "maxLength": 255,
      "title": "Name",
      "type": "string"
    },
    "sourceTemplateId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Template id this agent is based on.",
      "title": "Sourcetemplateid"
    },
    "sourceTemplateSlug": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Template slug this agent is based on.",
      "title": "Sourcetemplateslug"
    },
    "sourceTemplateVersion": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Template version this agent is based on.",
      "title": "Sourcetemplateversion"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "`draft` (default) or `published`.",
      "enum": [
        "draft",
        "published"
      ],
      "title": "Status"
    }
  },
  "title": "AgentCreateInput",
  "type": "object"
}
```

Example:

```json
{
  "config": {
    "language": "hi-IN",
    "llm_model": "gpt-4o-mini",
    "stt": "sarvam",
    "template_payload": {
      "greeting_message": "Namaste, main Acme Realty se Priya bol rahi hoon.",
      "system_prompt": "You are Priya from Acme Realty. Qualify the lead's budget and preferred area."
    },
    "tts": "sarvam",
    "voice": "priya"
  },
  "name": "Priya"
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "agent": {
    "config": {
      "language": "hi-IN",
      "llm_model": "gpt-4o-mini",
      "tts": "sarvam",
      "voice": "priya"
    },
    "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10",
    "language": "hi-IN",
    "name": "Priya",
    "rosterState": "in_training",
    "status": "draft",
    "takingCalls": false,
    "unpublishedChanges": false
  },
  "success": true
}
```

#### 400 Bad request: `bad_request`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 402 Payment required: `payment_required`.

Example (Your account does not have enough balance or an active plan for this request.):

```json
{
  "detail": "Your account does not have enough balance or an active plan for this request.",
  "error": {
    "code": "payment_required",
    "docUrl": "https://docs.callmitra.ai/errors/payment_required",
    "message": "Your account does not have enough balance or an active plan for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "billing_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `resource_not_found`.

Example (The requested resource was not found.):

```json
{
  "detail": "The requested resource was not found.",
  "error": {
    "code": "resource_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/resource_not_found",
    "message": "The requested resource was not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`.

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

#### 413 Payload too large: `payload_too_large`.

Example (The request body is too large.):

```json
{
  "detail": "The request body is too large.",
  "error": {
    "code": "payload_too_large",
    "docUrl": "https://docs.callmitra.ai/errors/payload_too_large",
    "message": "The request body is too large.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 422 Invalid parameters: `parameter_invalid`.

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`payment_required`](/errors/payment_required)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`resource_not_found`](/errors/resource_not_found)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`payload_too_large`](/errors/payload_too_large)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
