error tells you the specific cause in plain text. 10DLC responses that originate at the US registry add a second key, providerError. This page covers the Messaging API under https://api.vobiz.ai/api/v1/sms. For the rest of the platform (voice, numbers, accounts) see the API error reference.
Status codes
404 applies to resources that exist on another account as well as to ids that do not exist. The body is always {"error": "<resource> not found"}.Sending: 201, 202, 422 and 502
POST /messages creates one message record per recipient. The status code summarises the whole request, and the body is the first record created.
A message that was accepted but later failed on the network does not change the HTTP response; it changes the message
status to failed, with errorCode and errorMessage from the delivery report. Watch for it through webhooks or GET /messages/{id}.
Retrying safely with idempotencyKey
SetidempotencyKey on every send. If you retry a request with the same key, Vobiz returns the original message with 201 instead of sending again, whatever the first attempt’s outcome. The key is scoped to your account; with several recipients the key is applied per recipient as <key>:<to>.
Retry on 502 and 503 with the same key after a short delay. A 400, 402, 404, 409 or 422 describes something in the request or the account state, so fix the cause before retrying. The same advice applies to POST /broadcasts/{id}/launch: read the 422 message, fix the draft, launch again.
The providerError field
10DLC brand and campaign calls are relayed to the US 10DLC registry. When the registry rejects or cannot process a request, the response carries both keys:error is the message to show your users. providerError is an opaque diagnostic string: log it and quote it to support if you need help, but do not parse it or build logic on its contents. Status codes on these responses:
Validation that Vobiz performs before contacting the registry uses the
invalid request: ... prefix, for example invalid request: brandType is required or invalid request: toll-free campaigns use POST /v1/10dlc/campaigns/toll-free.
RCS senders and templates
The sender and template endpoints report most problems as400 with the platform’s message in error, for example provider create sender failed: .... GET /senders/{id} and GET /senders/{senderId}/templates/{templateName} return 404 for unknown ids.
Money-moving endpoints
POST /numbers/purchase debits your balance before buying the number. If the upstream provider then cannot complete the purchase, the response is 502 and the message states what happened to the money: number provider could not complete the purchase; your wallet has been refunded or ...; your refund is being processed by support. POST /numbers/{e164}/release ends the rental without a refund of the current period.
Handling errors in code
Next steps
Platform error reference
Status codes for the voice and account APIs.
Send a message
Request schema and response codes.
Before you go live
Compliance overview
Avoid registry rejections before they happen.
Messaging numbers
Buying, billing and number registration status.