# Errors

The Transactional HTTP API uses standard HTTP status codes. This page lists the ones you will encounter, what they mean and whether a retry is safe.

Every response carries a meaningful HTTP status code. A `2xx` means the request was accepted; anything else signals a problem your code should handle explicitly. Error bodies, when present, are JSON with a `message` field describing the failure.

## Status codes

### `400 Bad Request`

The request body is malformed or has the wrong shape. Not retryable — fix the payload first.

```http
HTTP/1.1 400 Bad Request
```

```json
{ "message": "Problems parsing JSON" }
```

```json
{ "message": "Body should be a JSON object" }
```

### `401 Unauthorized`

The token is missing, revoked or malformed. Not retryable with the same token — check the [Authentication](/transactional-api/http/authentication) guide.

```http
HTTP/1.1 401 Unauthorized
```

### `402 Payment Required`

The account has run out of balance. Not retryable until funds are topped up in the dashboard.

```http
HTTP/1.1 402 Payment Required
```

### `404 Not Found`

The resource (message id, token id, project) does not exist or is not visible to the current token.

```http
HTTP/1.1 404 Not Found
```

### `413 Request Too Large`

The request body exceeds the maximum accepted size. Not retryable — trim the payload.

```http
HTTP/1.1 413 Request Too Large
```

### `429 Too Many Requests`

You hit the per-endpoint rate limit. Retry after `X-RateLimit-Reset`. See [Rate limits](/transactional-api/http/rate-limits).

```http
HTTP/1.1 429 Too Many Requests
```

### `500 Internal Server Error`

Something broke on our side. Retry with exponential backoff; if the failure persists, contact support with the request id.

```http
HTTP/1.1 500 Internal Server Error
```

## Retry policy

> **Tip**: Retry `429` and `5xx` with exponential backoff, starting at 1 s and capping at a minute or so. Everything in the `4xx` range other than `429` means the request itself is wrong — retrying will not help.

## What's next

- **[Receiving DLRs](/transactional-api/http/dlrs)** — delivery reporting for messages that did leave the API successfully.
- **[API Reference](/transactional-api/http/reference)** — per-endpoint responses.