Talkr AI Documentation

Error format

All errors return a JSON body with a detail field:

{
  "detail": "Human-readable error message"
}

For request validation failures (status 422), detail is an array of field-level errors:

{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

HTTP status codes

Status	Meaning	Common causes
`400`	Bad Request	Missing required fields, invalid parameter values, unsupported operation
`401`	Unauthorized	Missing auth header, invalid or expired API key or JWT token
`403`	Forbidden	Valid credentials but the resource belongs to a different organization
`404`	Not Found	Resource ID does not exist or is not accessible to your organization
`409`	Conflict	Duplicate resource (e.g., email already registered)
`422`	Unprocessable Entity	Request body or query parameter failed schema validation
`429`	Too Many Requests	You've exceeded the rate limit — see Rate Limits below
`500`	Internal Server Error	Unexpected server-side failure
`501`	Not Implemented	Feature not supported in the current deployment

Workflow validation errors

When validating a workflow (or creating one with invalid nodes), the API returns structured errors that reference specific nodes, edges, or fields:

{
  "errors": [
    {
      "kind": "node",
      "id": "agent-1",
      "field": "data.prompt",
      "message": "Prompt cannot be empty"
    },
    {
      "kind": "edge",
      "id": "edge-3",
      "field": null,
      "message": "Edge target node does not exist"
    },
    {
      "kind": "workflow",
      "id": null,
      "field": null,
      "message": "Workflow must have exactly one Start Call node"
    }
  ]
}

Field	Type	Description
`kind`	`"node" \| "edge" \| "workflow"`	What the error applies to
`id`	string or null	Node or edge ID from the workflow definition
`field`	string or null	Dot-notation path to the specific field (e.g. `data.prompt`)
`message`	string	Human-readable description of the problem

Rate limits

Every API key has a request-rate limit to keep the platform stable for everyone. If you exceed it, you'll get a 429 response:

{
  "detail": "Rate limit exceeded, try again shortly."
}

The response includes a Retry-After header telling you how many seconds to wait before your next request. If you're not sending an API key (e.g. requests from the dashboard itself), the limit applies per IP address instead.

Telephony webhook callbacks (inbound call events from your telephony provider) are never rate-limited, so real calls are never affected.

Telephony errors

Telephony operations may fail with one of these named error types returned in the detail field:

Error	Description
`PROVIDER_MISMATCH`	The request was routed to the wrong telephony provider
`WORKFLOW_NOT_FOUND`	The workflow ID in the inbound URL does not exist
`ACCOUNT_VALIDATION_FAILED`	Your telephony provider credentials are invalid
`PHONE_NUMBER_NOT_CONFIGURED`	The phone number is not set up in your telephony account
`SIGNATURE_VALIDATION_FAILED`	Webhook signature verification failed (possible spoofed request)
`QUOTA_EXCEEDED`	Your organization has exceeded its usage quota
`GENERAL_AUTH_FAILED`	Generic authentication failure with the telephony provider

Tips for handling errors

Retry on 500 with exponential backoff — transient server errors can resolve on retry.
Do not retry 4xx — these indicate problems with your request that will not self-resolve.
Check detail carefully on 422 — the loc array pinpoints exactly which field failed validation.
Store API keys securely — a 401 on a previously working key likely means the key was archived.

Errors