Errors
Status codes and exact message strings the phone-numbers module returns.
Status codes
| Status | When | Exact body |
|---|---|---|
404 | Unknown number, or outside your account scope | {"success":false,"message":"Phone number configuration not found."} |
422 | More than one inbound routing target set | {"success":false,"message":"Choose only one inbound target — an assistant, a squad, or a workflow.","errors":{"vapi_assistant_id":["Only one inbound target may be set."]}} |
422 | Number has no upstream id yet | {"success":false,"message":"This phone number is not registered on the voice platform yet, so its configuration cannot be edited."} |
422 | Composition rejected by the live platform | {"success":false,"message":"<cleaned upstream error>","errors":{"fallback_destination.number":["…"]}} or the same shape keyed under server.url |
422 | Validation failed | {"message":"…","errors":{…}} — e.g. "The fallback number must be a valid phone number in E.164 format (e.g. +14155551234).", "A fallback phone number is required when the destination type is a number.", "A SIP URI is required when the destination type is SIP." |
502 | Live platform write failed | {"success":false,"message":"Failed to update the phone number. Please try again."} |
403 | Feature phone_numbers not enabled for the account | {"message":"This feature is not enabled for your account. Please contact your administrator.","feature":"phone_numbers"} |
Platform-wide 401/409/429 responses are documented once in the Introduction.