Errors

Error Envelope

{
  "status": 400,
  "message": "Only Tanzanian phone numbers are supported",
  "code": "BAD_REQUEST",
  "timestamp": "2026-09-09T14:00:00.000Z",
  "path": "/api/v1/api/messages/send",
  "error": "Only Tanzanian phone numbers are supported"
}

error can be a string, array, or object. details appears only when structured diagnostics are available.

Authentication

Requests fail before SMS processing when the API key is:

missing.
not prefixed with ntfy_.
malformed or invalid.
revoked or inactive.
expired.
not authorized for SMS.
not validated before the authentication dependency timeout.

Correct credentials before retrying.

Request Validation

Correct the request before retrying when:

required fields are missing.
canonical recipient format is not E.164 with leading +.
compatibility phone fields are empty or invalid after normalization.
content is empty or longer than 918 characters.
messages or phone_numbers is empty.
scheduledAt is not an ISO date-time.
all bulk recipients are unsupported.

Sender Failures

Failure	Status	Action
Sender cannot be found or is not approved for this customer	`404`	Verify the Portal sender identifier and ownership
Private sender belongs to another customer	`403`	Use a sender available to the API-key owner
Sender exists but is not approved	`422`	Wait for Portal approval or choose an approved sender
Sender usage limit is exhausted	`409`	Resolve the limit in the Portal

Credits

The send service debits calculated segments before persistence and provider dispatch. Insufficient-credit and payment-dependency errors originate from the account credit service.

Calculate segments before large sends.
Inspect balance and transaction activity in the Portal.
Do not blindly retry an uncertain send response.
Treat creditsDeducted and remainingBalance from batch responses as authoritative for that operation.

Provider Outcomes

HTTP success means the API completed its submission workflow; it is not proof of device delivery.

SENT means the provider accepted submission.
DELIVERED requires a later delivery update.
FAILED means submission or delivery failed.
Persist the message UUID and poll status when final delivery matters.

Status Lookup

Malformed, unknown, and cross-customer message IDs all return 403 Message not found or not authorized.

Verify:

the value is the UUID returned by the send response.
the same customer API key created the message.
the value is not a sender, provider, batch, or legacy numeric identifier.

Retry Guidance

Failure	Client action
Validation or sender state	Correct input or Portal setup; do not retry unchanged
Authentication	Replace or correct the API key
Insufficient credits	Fund the account before retrying
Status `403`	Verify UUID and customer ownership
Timeout or server error before a confirmed response	Reconcile possible submission before retrying

The public SMS request contract has no idempotency key. Retrying a send can produce duplicate messages and duplicate debits.

On this page