Reference

Errors

Errors use the HTTP status codes and a JSON body. Validation errors say which field failed.

Status	Meaning
`400`	The request is invalid: a field fails validation, or the request is refused (an unknown agent on a campaign, nothing to retry)
`401`	The API key is missing or unknown
`403`	The setting is not enabled on your account (`declinedStopRatio`)
`404`	The resource, or the entity you named, does not exist
`409`	A conflict: items of two entities, a name or external id already taken, an entity that still holds items, a tool still in use
`422`	A call flow references a tool that does not exist, or gives a looked-up `forwardCall` node the name of another tool
`5xx`	A server error: retry with a backoff, then write to `support@callshift.ai`

Validation errors

JSON

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      { "code": "invalid_string", "path": ["contacts", 0, "email"], "message": "Invalid email" }
    ]
  }
}

The issues are under error. path locates the field, here the email of the first contact.

Other errors

JSON

{ "error": "Campaign not found" }

Some conflicts say more, so that you can act on them:

Request	Extra field
Create an entity whose external id is taken	`existingEntityId`: the entity that holds it
Delete an entity that holds items	`usage`: its `agents`, `phoneNumbers`, `webhooks`
Delete a tool in use	`agents`: the agents that reference it