---
url: https://textme-docs.matat.io/reference/status-codes.md
description: >-
  Every value the top-level status field can take, grouped by cause, with what
  to do about each and the two blocklist codes that mean success.
---

# Status codes

The top-level `status` on every response. `0` means the API accepted the call; anything else means it did not. Except for the two blocklist codes noted below, which are how those operations report success.

This is the request-level scale. The `status` *inside* a delivery report transaction is a different vocabulary entirely, see [DLR statuses](./dlr-statuses.md).

## Success

| Status | Message | Meaning |
|---|---|---|
| `0` | *operation-specific* | The call was accepted. `message` describes what happened. `SMS will be sent`, `contact list successfully created`, and so on. |

::: warning Two blocklist operations succeed with a non-zero status
[`addNumBL`](../endpoints/blacklist.md) answers `946` when numbers were added, and [`rmNumBL`](../endpoints/blacklist.md) answers `944` when some of the numbers given were not on the blocklist. Both are normal outcomes, not failures. Special-case them, or a working integration will look broken.

| Status | Message | Operation |
|---|---|---|
| `944` | `X phone numbers Successfully deleted, Y Phone numbers not exist in blacklist` | `rmNumBL`, partial success |
| `946` | `number has successfully added to blacklist` | `addNumBL`, success |
:::

## Parsing and routing

| Status | Message | What to do |
|---|---|---|
| `1` | There was a problem parsing your XML | The document is malformed. An unclosed tag, a stray character, or a body that is not XML at all. Deterministic; fix the payload. |
| `2` | *names the missing field* | A required element is absent. The `message` says which one. |
| `7` | You can not send in this format, you need send group in 'bulk', For more - call to Customer Service. | The payload shape does not match the operation, typically several distinct messages sent through [`sms`](../endpoints/send.md) instead of [`bulk`](../endpoints/bulk.md). |
| `502` | action type not valid | An `action` value outside the allowed set, for [`getApiToken`](../endpoints/tokens.md) that means anything other than `new` or `current`. |
| `997` | Not a valid command sent | The root element is not a recognised operation. Check spelling, including the deliberately odd ones such as `getBlanceSubs`. |
| `998` | There was an unknown error in the request | Unclassified request failure. |
| `999` | Contact support | Server-side failure. Retry once with backoff, then escalate. |

## Authentication and permissions

| Status | Message | What to do |
|---|---|---|
| `3` | Username or password is incorrect and API token is invalid | The token is not recognised. See [Authentication](../guide/authentication.md). |
| `10` | Username or password is incorrect and Expired API token | The token has passed its `expiration_date`. Mint a new one. |
| `11` | API token is valid but doesn't match username or if you have newer token you should use it instead | The token belongs to a different username, or has been superseded. |
| `503` | username not exist in your account | The `user.username` is not an account you may act for. |
| `504` | current token not found | `action: current` on an account that has never had a token. Create the first one in the console. |
| `511` | you have not permission for this function | Authenticated, but the account is not entitled to this operation. |

## Account state

These can succeed later without any change to your request.

| Status | Message | What to do |
|---|---|---|
| `4` | Not enough credit | Top up. [`balance`](../endpoints/balance.md) reports what is left. |
| `5` | No permission to send SMS at this time | Outside the account's permitted sending hours. |
| `6` | Process failure | Transient server-side failure. Retry once with backoff. |
| `12` | When sending SMS: Not enough money **·** When verifying OTP code: Unverified code | Two unrelated meanings on one code. Read it against the operation you called. On [`validate_otp`](../endpoints/otp.md) it means the code did not verify. |
| `515` | Unverified source. For more information see: D4U.co.il/li/pmYra | The `source` is not a verified sender. See [Verified senders](../endpoints/verified-senders.md). |

## Destinations

| Status | Message | What to do |
|---|---|---|
| `8` | All numbers are on a blocked list | Every destination is blocklisted, so nothing was sent. Not a code fault. An audience one. |
| `9` | At least one of the destinations is too short or too long | A phone number does not match `5xxxxxxxx` / `05xxxxxxx`. |
| `714` | non valid content in parameter temp\_bl | `temp_bl` must be a whole number of days from 1 to 14. |
| `715` | All numbers have been temporarily blocked | Every destination was filtered out by `temp_bl`. |
| `988` | Contact list are entered not exist | A `cl_id` does not resolve. Check with [`getCL`](../endpoints/contact-lists.md). |

## Message content

| Status | Message | What to do |
|---|---|---|
| `980` | Invalid link | A `<link>` value is not a usable URL. |
| `981` | Error create hash | The short link could not be generated. Retry; escalate if it persists. |
| `986` | Add unsubscribe error - invalid value | `add_unsubscribe` accepts `2` (reply to opt out) or `3` (opt-out link). |
| `989` | The message is too long or too short **·** The campaign name is too long | The body exceeds 1005 characters or is empty, or `campaign_name` exceeds 50. |

## Campaigns

| Status | Message | What to do |
|---|---|---|
| `955` | Campaign already cancel | Already cancelled. Idempotent in effect, so usually safe to ignore. |
| `966` | Campaign already sent | Too late to cancel; the campaign has gone out. |
| `970` | Campaigns was not cancelled. Contact support | Cancellation failed server-side. |
| `977` | Campaign does not belong to customer or Not exist | Wrong `campaign_id`, or it belongs to another account. |

## Blocklist

| Status | Message | What to do |
|---|---|---|
| `933` | Phone or reason not valid | [`rmNumBL`](../endpoints/blacklist.md) needs a valid phone *and* a `reason`. |
| `944` | Some of numbers not in blacklist | Partial success on `rmNumBL`. See the note at the top of this page. |
| `946` | number has successfully added to blacklist | Success on `addNumBL`. See the note at the top of this page. |

## Sender verification

| Status | Message | What to do |
|---|---|---|
| `510` | invalid verify\_phone request: no phones to verify | [`verify_phone`](../endpoints/verified-senders.md) was called with no `phone` elements. |

## Sub-accounts

Returned by the reseller operations in [Subscribers](../endpoints/subscribers.md).

| Status | Message | What to do |
|---|---|---|
| `990` | Amount must be small amount of your credits | You cannot grant a sub-account more credit than you hold. |
| `991` | The amount must contain only digits | `amount` must be numeric. |
| `992` | The source is too long or too short | The default `source` for the sub-account is outside the 11-character limit. |
| `993` | The password is too long or too short | Password length rejected. |
| `994` | Username already exists | Pick a different `username`. |
| `995` | The username is too long or too short | Username length rejected. |
| `996` | The name is too long or too short | Display `name` length rejected. |