Errors

All errors follow a consistent JSON shape:

{
  "detail": "Human-readable description of what went wrong"
}

Some errors carry structured details:

{
  "detail": [
    {
      "loc": ["body", "predictive_target_abandon"],
      "msg": "must be between 0 and 0.030 (TRAI cap)",
      "type": "value_error"
    }
  ]
}

That’s Pydantic’s 422 format — field-level validation errors.

Status codes

Status	Meaning
200	Success
201	Created
204	Success, no body
400	Malformed request (rare — most validation uses 422)
401	Missing or bad API key
403	Key lacks the required scope (future)
404	Resource doesn’t exist OR belongs to another tenant
409	State conflict (e.g. `/predictive/pause` on a non-running campaign)
422	Validation error — body failed a Pydantic constraint
429	Rate-limited
500	Our bug. Email support with the request timestamp.
502/503/504	Upstream momentarily unavailable. Retry with backoff.

Tenant-scoped 404s

When you GET a resource that exists but belongs to another tenant, you get a 404, not a 403. We never want to confirm existence across tenant boundaries (otherwise an attacker could enumerate other customers’ campaign IDs).

Validation errors you’ll see often

`predictive_target_abandon > 0.030`

{
  "detail": [{
    "loc": ["body", "predictive_target_abandon"],
    "msg": "Input should be less than or equal to 0.03",
    "type": "less_than_equal"
  }]
}

TRAI caps abandon rate at 3.0%. We can’t accept a higher target.

Inverted ratio range

{
  "detail": "predictive_max_dial_ratio (1.5) must be >= predictive_min_dial_ratio (3.0)"
}

When you PATCH both ratio fields in the same payload, they must satisfy max >= min. PATCHing just one is always allowed (we defer to the DB CHECK).

Invalid phone

{"detail": "Invalid phone number"}

We only accept Indian numbers (10 digits, optional 0/91 prefix). For non-Indian use cases, contact us — cross-border dialing has its own compliance track.

Abandon rate exceeded (business-level)

Not an HTTP error — it’s a lifecycle event. When a predictive campaign’s abandon rate crosses its target for 60s sustained, the backend auto-pauses the campaign. You’ll see:

The campaign’s status flip to paused
A campaign.paused webhook with data.source = "abandon_rate_exceeded"

Re-enable via POST /api/campaigns/{id}/predictive/resume (dashboard JWT auth, not the v1 API key). See the operator runbook in your dashboard for guidance.

Get started

OAuth

Core concepts

Voice agents

SDKs

Integrations

Status codes

Tenant-scoped 404s

Validation errors you’ll see often

`predictive_target_abandon > 0.030`

Inverted ratio range

Invalid phone

Abandon rate exceeded (business-level)

​Status codes

​Tenant-scoped 404s

​Validation errors you’ll see often

​predictive_target_abandon > 0.030

​Inverted ratio range

​Invalid phone

​Abandon rate exceeded (business-level)

Status codes

Tenant-scoped 404s

Validation errors you’ll see often

`predictive_target_abandon > 0.030`

Inverted ratio range

Invalid phone

Abandon rate exceeded (business-level)