Errors & Rate Limits

Understand error responses and rate limits in the Twenty2 API.

Twenty2 uses standard HTTP status codes and returns consistent error objects so you can handle failures predictably in your integration.

Error Response Format

All errors follow this structure:

{
  "success": false,
  "error": {
    "code": "INVALID_ASSISTANT",
    "message": "The assistant_id provided does not exist or is not published.",
    "status": 400
  }
}

Field	Type	Description
`success`	boolean	Always `false` for errors
`error.code`	string	Machine-readable error code
`error.message`	string	Human-readable description of what went wrong
`error.status`	number	HTTP status code

HTTP Status Codes

Status	Meaning
`200`	Success
`400`	Bad Request — missing or invalid parameters
`401`	Unauthorized — API key is missing or invalid
`403`	Forbidden — API key lacks access to this resource
`404`	Not Found — the requested resource doesn't exist
`422`	Unprocessable Entity — request is well-formed but contains invalid values
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — something went wrong on Twenty2's end

Common Error Codes

Code	Status	Description
`UNAUTHORIZED`	`401`	API key is missing or invalid
`FORBIDDEN`	`403`	API key does not have access to this resource
`INVALID_ASSISTANT`	`400`	The `assistant_id` does not exist or is not published
`INVALID_NUMBER`	`400`	`from_number` or `to_number` is not a valid E.164 phone number
`CALL_NOT_FOUND`	`404`	No call found for the given `call_id`
`RATE_LIMIT_EXCEEDED`	`429`	Too many requests — slow down and retry
`INTERNAL_ERROR`	`500`	Unexpected server error — contact support if this persists

Rate Limits

Limit	Value
Requests per minute	60
Concurrent calls	3

If you exceed the rate limit you will receive a 429 response. Wait a moment and retry. For higher limits, contact the Twenty2 team.

Handling Errors — Best Practices

Always check success in the response before processing data
Use error.code for programmatic handling — not error.message which may change
Retry on 500 with exponential backoff — these are usually transient
Do not retry on 400 or 422 — fix the request first
On 429, wait at least 1 second before retrying

    const response = await fetch("https://api.twentytwo.in/v1/calls", {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ ... })
    });

    const data = await response.json();

    if (!data.success) {
      console.error(`Error [${data.error.code}]: ${data.error.message}`);
    } else {
      console.log("Call queued:", data.call_id);
    }

    import requests

    response = requests.post(
      "https://api.twentytwo.in/v1/calls",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={ ... }
    )

    data = response.json()

    if not data.get("success"):
      print(f"Error [{data['error']['code']}]: {data['error']['message']}")
    else:
      print("Call queued:", data["call_id"])

Was this page helpful?

Last updated 3 weeks ago

Built with Documentation.AI