Errors and limits

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

An error always returns the same shape: a stable code, for your program to act on, and a message for a person to read. Handle the code, never the text: the message can change, the code cannot.

json

{
  "error": {
    "code": "device_offline",
    "message": "Device dev_oppo_cph2577 has been offline since 14:02.",
    "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
`409`	the device is offline	wait, or send through another one
`429`	too many requests	wait for what Retry-After says
`5xx`	failure on our side	retry with increasing backoff

Error codes

Code	When it happens
`invalid_number`	the number is not in E.164, or does not exist
`message_too_long`	above 1530 characters
`device_offline`	the chosen phone is not connected
`device_not_found`	the deviceId does not belong to the account
`quota_exceeded`	this month's messages have run out
`rate_limited`	above 60 requests per minute
`invalid_key`	the key was revoked, or never existed

Limits

Limit	Value
`API requests`	60 per minute per key
`Sending per phone`	roughly 40 messages per minute
`Queue per phone`	5000 messages
`Body size`	256 kB

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

The API accepts 60 requests per minute, but an Android phone sends roughly 40 messages per minute. Accepting faster only grows the queue: for 10,000 messages count on about four hours on one phone, or split them across several.