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 }
  }
]
FieldTypeDescription
successbooleantrue when the request worked. Check this field first.
dataobject or arrayThe result. An empty array [] when the request failed or there is nothing to return.
errorsarrayError messages as text. Usually empty when success is true, but some endpoints add warnings here, for example IDs that were not found.
paginationobjectOnly on endpoints that return pages of results. See Pagination and limits.
response.codeintegerThe same value as the HTTP status code.
response.descriptionstringThe name of the status code, for example Bad Request.
response.datestringServer time of the response, YYYY-MM-DD HH:MM:SS.
apiobjectThe version, module and function that answered. It is empty when the path has no trailing slash.
userobjectThe 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

  1. Check the HTTP status code. Codes from 200 to 299 mean success.
  2. Check success. If it is false, show or log the items in errors.
  3. When success is true, still read errors. 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 422 with {"message": "Internal Server Error"} in errors.
  • One string. Some 503 responses, for example from Unsubscribe a number, have a string in errors, not an array.

HTTP status codes

CodeDescriptionWhat to do
200OKThe request worked. Read data.
400Bad RequestA parameter is missing or not valid, or a limit was reached. Read errors, correct the request and send it again.
401Authentication FailureThe API key is missing, wrong, expired or revoked. See Authentication.
402Payment RequiredYour balance is too low. Add funds in the app.
403ForbiddenYour account cannot do this now. Examples: the account is waiting for activation, or the daily sending limit is reached.
404Resource Not FoundThe item does not exist in your account, a search found nothing, or the endpoint path is wrong.
409ConflictThe request cannot be done now. Wait and try again.
422Unprocessable EntityAn unexpected error occurred while the server processed the request. Try again. If it continues, contact support with the time of the request.
500Internal Server ErrorA server error. Try again later.
503Service UnavailableA 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, 503 and network errors. Wait a few seconds, and wait longer after each failed try.
  • Do not retry 400, 401, 402, 403 or 404 without 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.