Reference

Errors and statuses

Two kinds of outcome matter: the HTTP response to your request, and the status of the message afterwards. This page covers both.

HTTP status codes

Status	Meaning	Retry?
`200 OK`	The request was accepted. For sends, this means queued, not delivered.	No
`400 Bad Request`	The body is invalid: a missing field, a wrong type, a malformed number.	No, fix the request
`401 Unauthorized`	Missing or invalid API key.	No
`403 Forbidden`	The key cannot use this endpoint or feature.	No
`404 Not Found`	Unknown path, or the resource (call, PIN, application) does not exist.	No
`429 Too Many Requests`	You are sending faster than your account allows.	Yes, with backoff
`5xx`	Something went wrong on our side.	Yes, with backoff

Error body

SMS and RCS endpoints answer errors with an errorCode you can branch on, a readable description, a suggested action and, for invalid requests, the list of violations with the field at fault.

SMS and RCS · 400 Bad Request

{  "errorCode": "E400",  "description": "Request cannot be processed.",  "action": "Check the syntax, violations and adjust the request.",  "violations": [    { "property": "messages[0].destinations[0].to", "violation": "must not be blank" }  ],  "resources": []}

Voice, Verify and the inbound SMS inbox use an older shape: a requestError.serviceException object with a messageId code (BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, TOO_MANY_REQUESTS, GENERAL_ERROR) and a text. The client helper reads both, so err.message is always filled.

Voice and Verify · 404 Not Found

{  "requestError": {    "serviceException": {      "messageId": "NOT_FOUND",      "text": "Not found"    }  }}

send.ts

import { pulsr, PulsrError } from "./client";try {  await pulsr("POST", "/sms/3/messages", { messages: [/* ... */] });} catch (err) {  if (err instanceof PulsrError) {    if (err.status === 429 || err.status >= 500) {      // Temporary: retry later with exponential backoff    } else {      // Permanent: fix the request, do not retry as is      console.error(err.status, err.message, err.body?.violations);    }  }  throw err;}

Message statuses

Send responses, delivery reports and logs describe each message with a status object, and reports add an error object. Branch on groupName and keep name for logs and support.

Status and error objects

{  "status": {    "groupId": 3,    "groupName": "DELIVERED",    "id": 5,    "name": "DELIVERED_TO_HANDSET",    "description": "Message delivered to handset"  },  "error": {    "groupId": 0,    "groupName": "OK",    "id": 0,    "name": "NO_ERROR",    "description": "No Error",    "permanent": false  }}

groupName	groupId	Meaning	Final?
`PENDING`	`1`	Accepted and on its way. `PENDING_ACCEPTED` right after the send, `PENDING_WAITING_DELIVERY` once handed to the operator.	No
`DELIVERED`	`3`	Received by the handset (`DELIVERED_TO_HANDSET`) or by the operator when the handset does not report back.	Yes
`UNDELIVERABLE`	`2`	The operator or handset refused it. The `error` object says why.	Yes
`EXPIRED`	`4`	The validity period ran out before the message could be delivered.	Yes
`REJECTED`	`5`	Pulsr did not send it: invalid destination, blocked sender, not enough credit or a blocked country.	Yes

Error groups

The error object in a report has its own groups. permanent: true means retrying the same message to the same number will fail again.

groupName	groupId	Typical cause
`OK`	`0`	No error.
`HANDSET_ERRORS`	`1`	The phone is off, out of coverage, its memory is full or it cannot display the message.
`USER_ERRORS`	`2`	The number does not exist, is inactive or has blocked the sender.
`OPERATOR_ERRORS`	`3`	The mobile network refused or failed to route the message.

HTTP status codes

Status	Meaning	Retry?
`200 OK`	The request was accepted. For sends, this means queued, not delivered.	No
`400 Bad Request`	The body is invalid: a missing field, a wrong type, a malformed number.	No, fix the request
`401 Unauthorized`	Missing or invalid API key.	No
`403 Forbidden`	The key cannot use this endpoint or feature.	No
`404 Not Found`	Unknown path, or the resource (call, PIN, application) does not exist.	No
`429 Too Many Requests`	You are sending faster than your account allows.	Yes, with backoff
`5xx`	Something went wrong on our side.	Yes, with backoff

Error body

SMS and RCS endpoints answer errors with an errorCode you can branch on, a readable description, a suggested action and, for invalid requests, the list of violations with the field at fault.

SMS and RCS · 400 Bad Request

{  "errorCode": "E400",  "description": "Request cannot be processed.",  "action": "Check the syntax, violations and adjust the request.",  "violations": [    { "property": "messages[0].destinations[0].to", "violation": "must not be blank" }  ],  "resources": []}

Voice and Verify · 404 Not Found

{  "requestError": {    "serviceException": {      "messageId": "NOT_FOUND",      "text": "Not found"    }  }}

send.ts

import { pulsr, PulsrError } from "./client";try {  await pulsr("POST", "/sms/3/messages", { messages: [/* ... */] });} catch (err) {  if (err instanceof PulsrError) {    if (err.status === 429 || err.status >= 500) {      // Temporary: retry later with exponential backoff    } else {      // Permanent: fix the request, do not retry as is      console.error(err.status, err.message, err.body?.violations);    }  }  throw err;}

Message statuses

Send responses, delivery reports and logs describe each message with a status object, and reports add an error object. Branch on groupName and keep name for logs and support.

Status and error objects

{  "status": {    "groupId": 3,    "groupName": "DELIVERED",    "id": 5,    "name": "DELIVERED_TO_HANDSET",    "description": "Message delivered to handset"  },  "error": {    "groupId": 0,    "groupName": "OK",    "id": 0,    "name": "NO_ERROR",    "description": "No Error",    "permanent": false  }}

groupName	groupId	Meaning	Final?
`PENDING`	`1`	Accepted and on its way. `PENDING_ACCEPTED` right after the send, `PENDING_WAITING_DELIVERY` once handed to the operator.	No
`DELIVERED`	`3`	Received by the handset (`DELIVERED_TO_HANDSET`) or by the operator when the handset does not report back.	Yes
`UNDELIVERABLE`	`2`	The operator or handset refused it. The `error` object says why.	Yes
`EXPIRED`	`4`	The validity period ran out before the message could be delivered.	Yes
`REJECTED`	`5`	Pulsr did not send it: invalid destination, blocked sender, not enough credit or a blocked country.	Yes

Error groups

The error object in a report has its own groups. permanent: true means retrying the same message to the same number will fail again.

groupName	groupId	Typical cause
`OK`	`0`	No error.
`HANDSET_ERRORS`	`1`	The phone is off, out of coverage, its memory is full or it cannot display the message.
`USER_ERRORS`	`2`	The number does not exist, is inactive or has blocked the sender.
`OPERATOR_ERRORS`	`3`	The mobile network refused or failed to route the message.