---
title: "Errors"
description: "HTTP status codes the API returns, and how to read error responses."
---

> Documentation Index
> Fetch the complete documentation index at: https://dev.touchsms.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

Always check the HTTP status code of every response. A `2xx` code means the request succeeded. A `4xx` code means something in the request needs fixing, and a `5xx` code means something went wrong on our side.

Send `Accept: application/json` with every request so errors always come back as JSON.

## Status codes

| Status | Meaning | What to do |
|---|---|---|
| `200` / `201` | Success. | Read the response body. |
| `204` | Success, no body (for example, after a delete). | Nothing. |
| `400` | The request can't be completed in the resource's current state, such as cancelling a verification that is already verified. | Read `message`. |
| `401` | Authentication failed: the API key is missing, invalid or disabled. | Check your [credentials](/get-started/authentication/). |
| `403` | The resource belongs to another account. | Check the ID. |
| `404` | The resource doesn't exist, or the endpoint path is wrong. | Check the URL and ID. |
| `405` | The HTTP method isn't allowed on this endpoint, for example a `GET` to `/v2/sms`. | Check the method in the [API reference](/api/). |
| `406` | The send needs more than your account has available. See below. | |
| `422` | Validation failed. | Read `errors` for the fields that failed. |
| `429` | Too many requests. | Back off and retry. See [Rate limits](/concepts/rate-limits/). |
| `5xx` | Server error. | Retry with backoff. If it persists, [contact support](/support/). |

Some endpoints document their own errors in the [API reference](/api/).

## Validation errors

A `422` response names each field that failed and why:

```json
{
  "message": "The messages field is required.",
  "errors": {
    "messages": ["The messages field is required."]
  }
}
```

## Insufficient balance

If your account doesn't have enough credits for a send, the whole request is rejected with `406` and nothing is sent:

```json
{
  "message": "Insufficient credits",
  "required": 102,
  "balance": 11,
  "is_postpaid": false
}
```

`required` is the number of credits the request needs, and `balance` is what your account has. Top up your account, or send fewer messages. Scheduled messages are not checked against your balance when you submit them.

## Per-message errors

When you send messages, a request can succeed while some of its messages are rejected. Rejected messages come back in `data.errors` with an `error_code` and an `error_help`. See [Sending messages](/guides/sending-messages/#per-message-errors) for the list of codes.

## Troubleshooting connection problems

If you don't receive a status code at all, there is probably a network problem between your server and ours. Check firewalls, proxies, DNS and outbound HTTPS from your server.

If you get an error status, read the response body first: it usually says exactly what is wrong. Still stuck? See [Support](/support/).

Source: https://dev.touchsms.com.au/concepts/errors/index.mdx