Errors and limits

What each code means and how many requests you can make.

Errors always have the same shape. Program against code, never against message: the text can change, the code cannot.

json

{
  "error": {
    "code": "device_not_found",
    "message": "Device dev_oppo_cph2577 not found.",
    "requestId": "req_01H8X2K9"
  }
}

HTTP statuses

Status	Meaning	What to do
`200`	accepted	nothing
`400`	the request is malformed	fix the body; retrying will not help
`401`	invalid or revoked key	create a new key
`402`	no messages left on the plan	wait for renewal or change plan
`404`	the device does not exist	check the deviceId in /devices
`429`	too many requests	slow down; the limit resets every minute
`5xx`	failure on our side	retry with the same Idempotency-Key

Error codes

Code	When it happens
`validation_error`	a field is missing or malformed
`invalid_number`	the number is not in E.164, or does not exist
`message_too_long`	above 10 segments (1530 GSM-7 characters, 670 Unicode)
`device_not_found`	the deviceId does not belong to the account
`quota_exceeded`	this cycle's messages have run out
`rate_limited`	above the request limit for this account
`invalid_key`	the key was revoked, or never existed

Limits

Limit	Value
`API requests`	60 per minute per key, multiplied by the phones connected to the account (up to 3000)
`Sending per phone`	roughly 30 messages per minute, set by the phone and the carrier
`Messages per cycle`	your plan's quota; every response tells you what is left
`Message length`	10 segments
`reference field`	200 characters

An offline phone does not reject the message

It goes into the queue and is sent when the phone comes back. The response says `deviceOnline: false` so you can tell the difference between "sent in a second" and "waiting for a phone". Leave out deviceId and the phone with the shortest queue is used.

The real limit is the phone's, not the API's

One phone sends roughly 30 messages per minute. Anything accepted faster than that waits in the queue.