Understanding errors

Scope of this format

Public SMS v2 operations share the error format described here. It does not automatically apply to SMS v1, internal Cloud interfaces or future products. The SMS v2 catalogue explains each code and the required action.

An error combines an HTTP status with an error JSON object. Field names, codes and messages remain in English, regardless of the portal language or Accept-Language header.

Example response to a message creation request without an authentication header:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Use Authorization: Bearer with an organization API key."
  }
}

Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.

Field	Purpose
error.code	Stable identifier to use in your handling logic.
error.message	Readable explanation for diagnosis. Do not depend on its exact wording.
error.details	Optional additional information, including field validation errors.
message_id	Optional top-level identifier for reading the affected message. Its presence does not prove acceptance or delivery.

Read HTTP and the code together

Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.

Status	Meaning for SMS v2
400	Invalid request: correct the body, field, header, timestamp or cursor.
401	Missing authentication or invalid key.
403	Missing capability, activation or sender authorization.
404	Route or resource not found within the key’s organization.
405	HTTP method not supported on this route.
406	Requested response type is incompatible with JSON.
409	Check the code: insufficient credits, idempotency conflict or processing in progress.
415	Body type incompatible with application/json.
500	Internal error; it does not prove the message was not sent.
502	Known provider rejection or unknown outcome, depending on the code.
503	Service or submission unavailable; retry handling depends on the code and any stored response.

A 201 for immediate sending means the provider accepted the SMS. A 202 for scheduling means the API accepted the schedule and reserved credits. Neither confirms delivery to the recipient: see SMS statuses.

Retry without duplicating

For message or batch creation, retain the path, body and Idempotency-Key from the first attempt. After a network interruption or transient error, retry with those same values and space out attempts. Respect Retry-After when supplied; its absence does not justify a rapid retry loop.

Idempotency can store an error response. Replaying it then does not send the message again. In particular, provider_result_unknown requires checking the message status and forbids automatic resubmission with another key. Follow the code-specific decision in the SMS catalogue, then the Idempotency and retries guide.

Retry rules for message and batch creation do not establish a shared idempotency mechanism for all operations. Contact management follows its create or update contract.

If the response has another format

A network interruption or a response from an HTTP intermediary may contain no usable JSON. Check the status and Content-Type before reading the body. Do not infer that nothing was sent from an empty response, an unknown code or an HTML page.

Retain the timestamp and timezone, method, path, status, code and identifiers useful for tracking. Redact secrets and personal data before contacting support.