DocsError codes

lead_required

This agent is configured to collect visitor details before it will answer, and the required fields have not been supplied.

On this page
428HTTP 428 · Lead Required

What it means#

This agent is configured to collect visitor details before it will answer, and the required fields have not been supplied.

Retry after fixing

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

What causes it#

  • The agent has a lead gate switched on and the visitor has not completed it.
  • A custom integration started a conversation without sending the gated fields.

How to fix it#

  • Read `details.missing` — it lists exactly which fields the gate wants.
  • Collect those fields and resend them on the contact before starting the turn.
  • If you did not intend a gate, turn it off in the agent's settings; it is off by default.

The details object#

This code carries a details object with more than the message can say:

`{ missing: [...] }` — the field names the gate is waiting on.

What the response looks like#

428 application/problem+json
{
  "error": {
    "code": "lead_required",
    "message": "This agent is configured to collect visitor details before it will answer, and the required fields have not been supplied",
    "details": { ... },
    "request_id": "7cb7f7862a82425d8e4c3fb8a497dfe6"
  },
  "type": "https://integrable.cloud/docs/errors/lead_required",
  "title": "Lead Required",
  "status": 428,
  "detail": "This agent is configured to collect visitor details before it will answer, and the required fields have not been supplied",
  "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.