Errors

Every error the API returns has one body, at every status code:

{
  "detail": {
    "message": "this agent has validation errors",
    "errors": ["llm: unknown model gpt-4.9"],
    "code": null
  }
}

All three fields are always present. message is one sentence you can show a person. errors lists the individual problems, and is [] (never absent or null) when there is only the message. Parse detail.message and detail.errors and your handler works for every failure. code is a stable identifier for an error your code is expected to branch on, and null on every other. Branch on code, never on the wording of message. The codes today all come from posting into a conversation: whatsapp_window_closed, voice_session_live, chat_ended, chat_open_elsewhere, idempotency_conflict, channel_unsupported, no_agent and messages_off (an agent was sent for a WhatsApp number or Telegram bot whose messages trigger is off; WhatsApp batches answer it too).

Status codes

Code	Meaning	Retry?
`200`	Success. Deletes answer `{"ok": true}` unless noted below	—
`201`	Created	—
`202`	Accepted, work continues in the background: `POST /v1/chats/{chat_id}/end`, `DELETE /v1/chats/{chat_id}`, `DELETE /v1/calls/{session_id}`, `DELETE /v1/conversations/{conversation_id}`	—
`204`	`DELETE /v1/calls/{session_id}/recording`	—
`302`	The recording endpoints redirect to a short-lived signed URL. Follow it	—
`400`	Well formed, rejected by a rule: unknown model, unpublished tool, broken operation tree. `errors` lists each problem	No. Fix the request
`401`	No credential, a malformed or revoked one, or a user no longer in this workspace	No
`402`	The workspace is out of credits; a new call or chat cannot start	After adding credit
`403`	Valid credential, but the role may not do this	No. Use a role that can
`404`	No such resource in this workspace. `No such operation on this API.` means the path matched no endpoint	No
`409`	The resource’s current state forbids this: a name already taken, a batch already finished, a call still in progress	Once the state changes
`422`	The request did not match the schema. One `field.path: problem` line per issue	No
`500`	Unhandled failure on our side	Yes, with backoff
`502`	A provider Talqing called for you did not answer or refused: a voice or avatar catalog, provider-key verification, an integration, the code-execution service	Yes, with backoff
`503`	A dependency is briefly unavailable (text-execution queue, CoPilot, payment checkout), or the requested region is not hosted on this deployment	Yes, with backoff, except the region case

422: schema validation

Each line is field.path: problem, with the body/query/path prefix stripped, so the path matches the key you sent. When there is exactly one problem, that line is also the message; with several, message is invalid request.

{
  "detail": {
    "message": "invalid request",
    "errors": [
      "config.channel: Input should be 'voice', 'video' or 'text'",
      "config.llm.model: Field required"
    ]
  }
}

A limit above an endpoint’s ceiling is a 422, not a silent clamp.

401 versus 403

Code	Means	Do
`401`	The credential is bad, revoked, or its user left the workspace	Fix the credential
`403`	The role is too low: `your role is view-only — ask an organization admin for editor access`, or `only an organization admin can do this`	Change the role, or use another credential

402: out of credits

Returned only by the four operations that start a billable session: POST /v1/calls/token, POST /v1/calls/outbound, POST /v1/calls/{session_id}/resume and POST /v1/chats. Sessions already running are unaffected.

{
  "detail": {
    "message": "This workspace is out of credits. Add credits in Settings → Billing to start new calls. Calls already in progress are unaffected.",
    "errors": []
  }
}

An inbound phone call or media stream refused for credit never reaches an HTTP caller: it reads back with close_reason: "insufficient_credits". A batch pauses instead of failing. See pricing and credits.

Validation results are not errors

POST /v1/agents/{agent_id}/validate, POST /v1/tools/{tool_id}/validate and POST /v1/tasks/{task_id}/validate answer 200 with {"errors": [...], "warnings": [...]}, both always present. Errors block a publish; warnings do not, and a successful publish returns them in warnings. Publishing with errors present is a 400 carrying the same lines in detail.errors. See validation.

Retrying

Retry 500, 502 and 503 with exponential backoff. Every other code is a verdict on the request; sending it again changes nothing. Neither SDK retries for you.

Only two endpoints take an idempotency key: POST /v1/task-runs and POST /v1/conversations/items. Resending the same idempotency_key returns the original with Idempotent-Replayed: true. Any other retried POST is a second request: a second call placed, email sent.

Elsewhere:

Chat messages dedupe. POST /v1/chats/{chat_id}/messages requires a client_message_id UUID you generate. Re-sending the same id returns the original turn instead of posting twice.
Names are unique. A retried create of an agent, tool or task answers 409 (an agent with that name already exists). Treat it as success and read the resource.
Read before re-dialling. After a timeout on POST /v1/calls/outbound, list calls by contact_key or batch_id before placing it again.
Let batches retry. Call batches carry their own max_attempts and retry_after_minutes.

How the SDKs raise

Both SDKs raise one error type for every non-2xx response, carrying the envelope’s fields.

curl -sS -o response.json -w '%{http_code}\n' \
  -X POST https://api.talqing.com/v1/agents/$AGENT_ID/publish \
  -H "Authorization: Bearer $TALQING_API_KEY"
jq -r '.detail.message, (.detail.errors[] | " - " + .)' response.json

import { TalqingApiError } from "@talqing/sdk";

try {
  await talqing.agents.publish({ agent_id: agentId });
} catch (error) {
  if (!(error instanceof TalqingApiError)) throw error; // never reached the API
  console.error(error.status, error.message);
  for (const problem of error.errors) console.error(" -", problem);
}

from talqing import TalqingAPIError

try:
    talqing.agents.publish(agent_id)
except TalqingAPIError as error:
    print(error.status_code, error)
    for problem in error.errors:
        print(" -", problem)

	TypeScript `TalqingApiError`	Python `TalqingAPIError`
Status	`.status`	`.status_code`
Message	`.message`	`str(error)`
Problems	`.errors: string[]`	`.errors: list[str]`
Raw response	`.response: Response`	`.response: httpx.Response`
Decoded `detail`	—	`.detail`

A request that never got a response (DNS, abort, offline) is not a TalqingApiError in TypeScript: the transport’s own error is rethrown. instanceof TalqingApiError holds across the ESM and CommonJS builds. TalqingClient also takes onUnauthorized, called once on any 401 before the error is thrown.

Limits

Sizes, counts and timeouts the API enforces.

Authentication

Tokens, roles, and where 401 and 403 come from.

Using the API

Endpoints

Status codes

422: schema validation

401 versus 403

402: out of credits

Validation results are not errors

Retrying

How the SDKs raise

Limits

Authentication

​Status codes

​422: schema validation

​401 versus 403

​402: out of credits

​Validation results are not errors

​Retrying

​How the SDKs raise

Limits

Authentication

Status codes

422: schema validation

401 versus 403

402: out of credits

Validation results are not errors

Retrying

How the SDKs raise