Documentation

Errors

Ruut Voice uses standard HTTP status codes. Errors return a JSON body with a code and message.

Error format

HTTP/1.1bash


HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 21211,
  "message": "The 'To' number is not a valid phone number.",
  "more_info": "https://voice.ruut.chat/docs/reference/errors"
}

HTTP status codes

Status	Meaning
`400`	Bad request — invalid parameters or validation failure.
`401`	Unauthorized — missing or invalid credentials.
`403`	Forbidden — authenticated but not permitted (e.g. unverified source number).
`404`	Not found — resource doesn't exist.
`409`	Conflict — state conflict (e.g. call already accepted).
`429`	Too many requests — rate limit exceeded.
`500`	Internal server error — retry with backoff.

Common validation errors

Parameter	Type	Description
`invalid_phone_number`	The `To`/`From` number isn't valid E.164.
`unverified_source_number`	`From` isn't a number you own (or a verified caller ID).
`invalid_sip_destination`	The SIP host isn't your SIP domain or an allowlisted host.
`sip_extension_not_found`	The SIP user doesn't match a provisioned agent extension.
`invalid_twiml`	The inline TwiML is malformed or lacks a `<Response>` root.
`destination_not_allowed`	The destination violates an account or fraud allowlist.
`rate_limit_exceeded`	CPS or per-minute call limit exceeded.

Handling with the SDK

Examplets


import { RuutApiError } from "@ruut/voice-sdk";

try {
  await client.calls.create({ to: "+…", from: "+…", twiml });
} catch (err) {
  if (err instanceof RuutApiError) {
    console.error(err.status, err.code, err.message, err.requestId);
  }
}