# Errors

> Error format and the stable error codes of the API.


# Errors

Every error has the same shape and an HTTP status:

```json
{
  "error": {
    "code": "missing_inputs",
    "message": "Missing inputs: amount",
    "details": ["amount"]
  }
}
```

`code` is stable: branch on it, not on `message`. `details` is present when there is something to point at (fields, contacts, current revision).

| HTTP | Code                                                                | Meaning                                                                                           |
| ---- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| 400  | `invalid_request`                                                   | The body or query does not match the schema; `details` lists paths                                |
| 400  | `invalid_agent`                                                     | The agent document breaks a rule; `details` has `path` and `message` per problem                  |
| 400  | `missing_inputs`, `invalid_inputs`, `unknown_inputs`                | The call's inputs do not match the agent                                                          |
| 400  | `not_outbound_agent`, `not_inbound_agent`                           | Wrong agent type for the operation                                                                |
| 400  | `different_account`                                                 | The agent belongs to another account (routing a number)                                           |
| 409  | `client_has_numbers`                                                | A client still has active numbers: disable them or route them to another agent before deleting it |
| 400  | `invalid_callback_url`                                              | Not HTTPS, has credentials, or not public                                                         |
| 400  | `test_number_required`, `test_number_in_live_mode`                  | Mode and number do not match                                                                      |
| 400  | `invalid_contacts`                                                  | A campaign contact is invalid; `details` has `index`, `code`, `message`                           |
| 400  | `caller_id_not_owned`                                               | `calling.callerId` is not one of the account's numbers                                            |
| 400  | `webhook_secret_missing`                                            | Create the signing secret before using webhook delivery                                           |
| 400  | `email_not_configured`                                              | Email delivery is not available on this server                                                    |
| 400  | `invalid_cursor`, `invalid_json`, `payload_too_large`               |                                                                                                   |
| 401  | `missing_api_key`, `invalid_api_key`                                |                                                                                                   |
| 403  | `partner_only`, `forbidden`                                         | The operation needs an account key                                                                |
| 404  | `not_found`, `client_not_found`                                     | Missing, or not visible to this key (including the other mode)                                    |
| 409  | `revision_conflict`                                                 | The draft changed; `details.revision` is the current one                                          |
| 409  | `agent_not_published`, `agent_archived`, `type_immutable`           |                                                                                                   |
| 409  | `suppressed`                                                        | The number is on the do-not-call list                                                             |
| 409  | `call_already_started`, `not_cancellable`, `invalid_campaign_state` |                                                                                                   |
| 409  | `duplicate`                                                         | Unique value already used                                                                         |
| 500  | `internal_error`                                                    | Retry with the same `Idempotency-Key`                                                             |