Skip to main content
Every error from the Messaging API is a flat JSON object with one message:
The HTTP status code tells you the class of problem; 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

Set idempotencyKey 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.
Retrying a send without an idempotencyKey can deliver the same message twice and charge you twice. Make the key part of your request from the start.

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 as 400 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.
Purchases, releases and broadcast launches spend money or send real messages. Run them only with your own credentials and after confirming the request is what you intend.

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.