API guide
Responses and errors
All v1 endpoints return JSON in the same format. This page tells you how to read a response, how to find out if a request failed and what each HTTP status code means.
The response envelope
The body is a JSON array with one object. Always read the first item: body[0].
[
{
"success": true,
"data": { "id": 347617, "name": "UK customers", "status": "Finished" },
"errors": [],
"pagination": { "limit": 100, "offset": 0, "total": 19360 },
"response": { "code": 200, "description": "OK", "date": "2026-11-16 13:59:02" },
"api": { "version": "v1", "module": "lists", "function": "info" },
"user": { "id": 12345 }
}
]
| Field | Type | Description |
|---|---|---|
success | boolean | true when the request worked. Check this field first. |
data | object or array | The result. An empty array [] when the request failed or there is nothing to return. |
errors | array | Error messages as text. Usually empty when success is true, but some endpoints add warnings here, for example IDs that were not found. |
pagination | object | Only on endpoints that return pages of results. See Pagination and limits. |
response.code | integer | The same value as the HTTP status code. |
response.description | string | The name of the status code, for example Bad Request. |
response.date | string | Server time of the response, YYYY-MM-DD HH:MM:SS. |
api | object | The version, module and function that answered. It is empty when the path has no trailing slash. |
user | object | The id of your account. Not included when authentication failed. |
Dates
All dates use the format YYYY-MM-DD HH:MM:SS in SMSEdge server time. Server time is not UTC. To find the difference, compare response.date with the Date HTTP header, which is in GMT.
Find out if a request failed
- Check the HTTP status code. Codes from 200 to 299 mean success.
- Check
success. If it isfalse, show or log the items inerrors. - When
successistrue, still readerrors. Some endpoints use it for warnings about part of the request.
const res = await fetch(url, { headers: { 'X-API-KEY': key } })
const [body] = await res.json()
if (!body.success) {
const errors = Array.isArray(body.errors) ? body.errors : [body.errors]
throw new Error(`SMSEdge ${body.response.code}: ${errors.join('; ')}`)
}
return body.data
Error example
[
{
"success": false,
"data": [],
"errors": ["List with specified id [1] was not found"],
"response": { "code": 404, "description": "Resource Not Found", "date": "2026-11-16 13:59:03" },
"api": { "version": "v1", "module": "lists", "function": "info" },
"user": { "id": 12345 }
}
]
Other forms of errors
Most endpoints put error messages in an array of strings. A small number of responses use a different form, so make your code accept all of them:
- Object with parameter names. Validation errors from Set webhook URLs use the parameter as the key, for example
{"dlr_url": "Webhook Url is not a valid URL."}. - Object with a message. An unexpected server error returns HTTP
422with{"message": "Internal Server Error"}inerrors. - One string. Some
503responses, for example from Unsubscribe a number, have a string inerrors, not an array.
HTTP status codes
| Code | Description | What to do |
|---|---|---|
200 | OK | The request worked. Read data. |
400 | Bad Request | A parameter is missing or not valid, or a limit was reached. Read errors, correct the request and send it again. |
401 | Authentication Failure | The API key is missing, wrong, expired or revoked. See Authentication. |
402 | Payment Required | Your balance is too low. Add funds in the app. |
403 | Forbidden | Your account cannot do this now. Examples: the account is waiting for activation, or the daily sending limit is reached. |
404 | Resource Not Found | The item does not exist in your account, a search found nothing, or the endpoint path is wrong. |
409 | Conflict | The request cannot be done now. Wait and try again. |
422 | Unprocessable Entity | An unexpected error occurred while the server processed the request. Try again. If it continues, contact support with the time of the request. |
500 | Internal Server Error | A server error. Try again later. |
503 | Service Unavailable | A temporary error. Nothing was changed. Try again after a short wait. |
A 404 with success: false does not always mean a mistake. For example, Get unsubscribers returns 404 when you have no unsubscribers. Treat it as an empty result.
Retries
- Retry
500,503and network errors. Wait a few seconds, and wait longer after each failed try. - Do not retry
400,401,402,403or404without a change. The same request gives the same error. - A send request that timed out can still have sent the message. Before you retry it, check the Sending report, or you can send the message two times.