> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squawkvoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and Rate Limits

> Status codes, error bodies and rate limits for the SquawkVoice API

## 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](https://docs.squawkvoice.ai/api-reference/on-demand-calls/place-call.md). |
| `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](https://docs.squawkvoice.ai/api-reference/authentication.md#when-a-key-is-refused). |
| `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](#rate-limits). |
| `500` | Something went wrong on our side. Retry later, and contact [support@squawkvoice.ai](mailto: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`:

```json theme={null}
{
  "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:

```json theme={null}
{ "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:

```json theme={null}
{ "status": "error", "message": "Too many requests, please try again later." }
```

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

## Retrying Safely

| Request | Safe to retry? |
| - | - |
| [Get guidelines](https://docs.squawkvoice.ai/api-reference/agents/get-guidelines.md) | Yes. |
| [Replace guidelines](https://docs.squawkvoice.ai/api-reference/agents/replace-guidelines.md) | Yes. Sending the same text again leaves the same result. |
| [Publish an agent](https://docs.squawkvoice.ai/api-reference/agents/publish-agent.md) | 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](https://docs.squawkvoice.ai/api-reference/agents/get-publish-status.md), [Get live version](https://docs.squawkvoice.ai/api-reference/agents/get-live-version.md) | Yes. |
| [Cancel a call](https://docs.squawkvoice.ai/api-reference/on-demand-calls/cancel-call.md) | Yes. A repeat returns `200` with `already_cancelled: true`. |
| [Place a call](https://docs.squawkvoice.ai/api-reference/on-demand-calls/place-call.md) | **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.