Errors and Rate Limits

Status Codes

Status	Meaning
`200`	The request succeeded.
`202`	The request was accepted and will be acted on later, as when you place a call.
`400`	The request body or a parameter is invalid. The message says which field.
`401`	The API key is missing, unknown, expired or revoked. See Authentication.
`403`	The campaign or agent isn’t in your account.
`404`	The campaign, agent, contact or publish doesn’t exist.
`409`	The request conflicts with one already running, such as a publish started while another publish of the same agent is running.
`422`	The request is valid but can’t be carried out, for example a postcode that can’t be matched to a timezone.
`429`	Too many requests. See Rate Limits.
`500`	Something went wrong on our side. Retry later, and contact support@squawkvoice.ai if it continues.

Each endpoint page lists the statuses it returns, with an example body for each.

Error Bodies

Most errors have success: false and a readable error, sometimes with details:

{
  "success": false,
  "error": "Invalid request body",
  "details": "Unknown field(s): instructions. Only \"guidelines\" can be set."
}

A few carry message instead of error, such as an agent that doesn’t exist:

{ "message": "Assistant not found." }

Read error, and fall back to message. The text is for people: branch on the status code, not on the wording.

Rate Limits

Requests are rate limited. Every response carries these headers:

Header	Meaning
`RateLimit-Limit`	Requests allowed in the current window.
`RateLimit-Remaining`	Requests left in the current window.
`RateLimit-Reset`	Seconds until the window resets.

Go over the limit and you get a 429 with a Retry-After header giving the seconds to wait:

{ "status": "error", "message": "Too many requests, please try again later." }

Wait at least that long before you retry, and back off further if the 429s continue.

Retrying Safely

Request	Safe to retry?
Get guidelines	Yes.
Replace guidelines	Yes. Sending the same text again leaves the same result.
Publish an agent	Yes, if the draft hasn’t changed. A repeat while the publish runs returns `409` with its `poll_url`, and a repeat after it finishes returns `400` with nothing to publish; neither creates another version. If the draft was edited in between, the repeat publishes those edits as the next version.
Get publish status, Get live version	Yes.
Cancel a call	Yes. A repeat returns `200` with `already_cancelled: true`.
Place a call	No. There is no idempotency key, so a retried request places a second call.

If a request to place a call times out, don’t send it again blind. Check On-Demand activity on the campaign’s On-Demand tab in Studio first, or accept that the contact may be called twice.

Overview

On-Demand Calls

Agents

Status Codes

Error Bodies

Rate Limits

Retrying Safely

​Status Codes

​Error Bodies

​Rate Limits

​Retrying Safely

Status Codes

Error Bodies

Rate Limits

Retrying Safely