Error Reference

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "invalid_phone_number",
    "message": "The phone number '+1234' is not a valid E.164 number.",
    "param": "to",
    "doc_url": "https://cloudvno.com/developers/docs/errors/reference#invalid_phone_number"
  }
}

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded
201 Created	Resource created successfully
204 No Content	Request succeeded, no body
400 Bad Request	Invalid parameters
401 Unauthorized	Invalid or missing API key
403 Forbidden	Insufficient permissions for this operation
404 Not Found	Resource not found
422 Unprocessable Entity	Valid format but business logic error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	CloudVNO server error
503 Service Unavailable	Temporary outage

Error Codes

Authentication Errors

Code	Description	Resolution
unauthorized	API key missing or invalid	Check your API key in the Authorization header
api_key_revoked	API key has been revoked	Generate a new API key in the dashboard
insufficient_permissions	API key lacks required permission	Add the required permission to your API key

Messaging Errors

Code	Description	Resolution
invalid_phone_number	Destination number is not valid E.164	Validate and format numbers to E.164 (+[country][number])
number_not_sms_capable	Destination number cannot receive SMS	Use a voice call instead, or check number type
message_too_long	Message body exceeds character limit	Split into multiple messages or use MMS
from_number_not_owned	Sending number not in your account	Check the from number or provision one
unsubscribed	Recipient has opted out	Do not send to opted-out numbers
carrier_blocked	Carrier rejected the message	Check message content for spam triggers

Voice Errors

Code	Description	Resolution
call_rejected	Destination rejected the call	Normal — destination hung up or blocked
no_answer	Call was not answered	Expected — implement retry logic if needed
busy	Destination is busy	Retry later
invalid_twiml	Invalid call instruction XML	Check your webhook response format

Number Errors

Code	Description	Resolution
number_not_available	Requested number has been taken	Search for another available number
country_not_supported	Country not available for provisioning	Check supported countries list
regulatory_requirements	Address verification required for this country	Submit required regulatory documents in dashboard