Errors

Every error has the same shape and an HTTP status:

{
  "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`