Guide

Errors

The API uses HTTP status codes and answers every failure with a small JSON body. The status tells your code what to do; the message tells a person what went wrong.

Error body

Field	Type	Meaning
`message`	string	One sentence saying what was wrong.
`error`	string	The name of the status, such as `Bad Request`. Missing on `429` and `500`.
`statusCode`	number	The HTTP status again.

Branch on the HTTP status, not on the text of message. Messages are for logs and for people, and their wording can change.

400ResponseCaptured

{  "message": "to must be a phone number in international format, e.g. \"+919876543210\".",  "error": "Bad Request",  "statusCode": 400}

429ResponseCaptured

{  "statusCode": 429,  "message": "Rate limit of 120 requests per minute exceeded."}

Status codes

Status	Meaning	When
`200`	OK	A read succeeded, or a message was answered.
`201`	Created	A conversation was started (`POST /v1/conversations`).
`202`	Accepted	A call was placed and is ringing (`POST /v1/calls`). The result comes later.
`204`	No Content	A call was hung up or a conversation ended.
`400`	Bad Request	The request was wrong, or the project is not set up for it. See below.
`401`	Unauthorized	The key is missing, malformed, unknown, expired or revoked. See Authentication.
`404`	Not Found	The agent or call does not exist in the key's project, or the path is not an endpoint.
`409`	Conflict	A conversation message arrived while the previous one was still being answered.
`410`	Gone	The conversation has ended, expired, or was lost in a restart.
`422`	Unprocessable Entity	The agent's flow has an error and cannot run. The message quotes the first error.
`429`	Too Many Requests	The key made more than 120 requests in a minute. See Rate limits.
`500`	Internal Server Error	Something unexpected failed on the server.
`502`	Bad Gateway	The language model could not be reached during a conversation. The conversation is closed.
`503`	Service Unavailable	Phone calls are unavailable because the server has no public URL configured.

What a 400 means

A 400 covers the most ground. It is returned when:

a required body field is missing or of the wrong type: agentId, to, text;
to is not a number in international format;
one of the flow's variables has no value;
an :id in the path is not a UUID, or the body is not valid JSON;
provider is not twilio or exotel, or model is not <provider>:<model> naming a known provider;
something the request needs is not connected: a telephony provider, a speech provider, or the model's provider;
the telephony provider refused to place the call (its own message is passed on);
you asked to hang up a call that was placed through Exotel.

400ResponseCaptured

{  "message": "Missing variables: driver_name, company, route, planned_eta",  "error": "Bad Request",  "statusCode": 400}

400ResponseCaptured

{  "message": "Anthropic is not connected. Add its API key under Integrations.",  "error": "Bad Request",  "statusCode": 400}

400ResponseCaptured

{  "message": "Validation failed (uuid is expected)",  "error": "Bad Request",  "statusCode": 400}

Known issues

This is an early build. These behaviours were found while writing these docs and are described as they are today, not as they should be.

A malformed agent id returns 500, not 400. The three requests on the right do this. A well-formed id that does not exist correctly returns 404.
Conversation variables are all-or-nothing. One non-string value makes POST /v1/conversations ignore every variable. See Start a conversation.

500ResponseCaptured

{  "statusCode": 500,  "message": "Internal server error"}

POST /v1/calls: agentId is a string but not a UUID
POST /v1/conversations: agentId is a string but not a UUID
GET /v1/calls?agentId=: The value is not a UUID