INVALID_PHONE_NUMBER - Devotel Orbit Documentation

What this error means

INVALID_PHONE_NUMBER is returned with HTTP status 422 when a phone number field in your request — most commonly to_number or from_number on a message or call — is not a valid E.164 number. The request is not queued or partially processed; nothing is sent and no credits are deducted. Every response for this error carries this page’s address in meta.docs_url:

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "to_number must be a valid E.164 phone number"
  },
  "meta": {
    "request_id": "req_01J9ZKQ3V8",
    "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_PHONE_NUMBER"
  }
}

Cause

Orbit accepts phone numbers only in E.164 format: a leading +, then the country code and subscriber number as digits only — no spaces, dashes, parentheses, or leading zeros beyond the country code. The most common causes are:

Submitted value	Why it fails
`4155552671`	Missing the country code
`+1 (415) 555-2671`	Spaces and parentheses are not allowed
`0014155552671`	International dial prefix instead of `+`
`+14155552671 ext. 123`	Extensions are not part of E.164
`+0000000000`	Not a routable country code

How to fix it

Normalize to E.164 before sending. Strip formatting characters and store the number as + + country code + subscriber number, e.g. +14155552671 for a US number.
Always include the country code, even for domestic sends. A number that works in a local dialler is not valid on its own.
Validate early. A permissive check like ^\+[1-9]\d{1,14}$ catches most malformed values before they reach the API.
Clean stored contacts in bulk. If the error appears on numbers imported from a CRM or CSV, run a normalization pass over the contact list rather than patching sends one by one.

Once the number is valid E.164, retry the original request unchanged — the rest of the payload was accepted and does not need to be rewritten.

Error Code Reference — every code with its HTTP status, cause, and remediation.
Error Handling Examples — response-envelope handling patterns in code.

​What this error means

​Cause

​How to fix it

​Related

What this error means

Cause

How to fix it

Related