DocsError codes

handoff_disabled

A visitor asked to be passed to a person, but this agent has no human handoff configured.

On this page
422HTTP 422 · Handoff Disabled

What it means#

A visitor asked to be passed to a person, but this agent has no human handoff configured.

Retry after fixing

Retrying unchanged will not help. Correct the cause, then send it again.

What causes it#

  • `handoff_enabled` is off for the agent.
  • The handoff destination was removed and the feature switched itself off.

How to fix it#

  • Enable handoff on the agent and set a destination — a Slack channel, an inbox, or a webhook.
  • If handoff is deliberately off, handle this code in your client and tell the visitor what else they can do, rather than surfacing a raw error.

What the response looks like#

422 application/problem+json
{
  "error": {
    "code": "handoff_disabled",
    "message": "A visitor asked to be passed to a person, but this agent has no human handoff configured",
    "request_id": "7cb7f7862a82425d8e4c3fb8a497dfe6"
  },
  "type": "https://integrable.cloud/docs/errors/handoff_disabled",
  "title": "Handoff Disabled",
  "status": 422,
  "detail": "A visitor asked to be passed to a person, but this agent has no human handoff configured",
  "instance": "/api/agents/01a0652b-3713-7ea1-a6c9-2e895389ec34"
}

Branch on error.code, not on the message — the code is stable, the sentence is not. Log request_id either way.

Still stuck#

Quote the request_id from the response — hello@integrable.cloud. It is what lets us find the exact request. The full list of codes is at Error codes, and the conventions every endpoint shares are in Retries, versioning and limits.

Something unclear or missing? Tell us and we’ll fix it.