Errors

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

Error format

12345678HTTP/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.

Examples of API errors

Code	Meaning	Context
`20003`	Authentication failed or the token lacks a required scope	HTTP 401
`20021`	Insufficient funds	Billing gate, HTTP 403
`30002`	Account suspended	Authentication or account authorization
`20429`	Too many requests	Request throttle, HTTP 429

Validation and fraud responses vary by endpoint. Inspect the returned code, message, and HTTP status; a fraud response can also include fraud_reason.

Handling with the SDK

123456789import { 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);
  }
}