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

# Error Codes

> API error codes and how to handle them

The Trackly SMS API uses standard HTTP status codes and returns detailed error information in the response body.

## Error Response Format

All errors follow this format:

```json theme={null}
{
  "error": "Human-readable error message",
  "code": "machine_readable_code"
}
```

## HTTP Status Codes

| Status | Meaning                                      |
| ------ | -------------------------------------------- |
| `200`  | Success                                      |
| `201`  | Created (for POST requests)                  |
| `400`  | Bad Request - Invalid parameters             |
| `401`  | Unauthorized - Invalid credentials           |
| `404`  | Not Found - Resource doesn't exist           |
| `429`  | Too Many Requests - Rate limit exceeded      |
| `500`  | Internal Server Error - Something went wrong |

## Authentication Errors (401)

| Code                  | Message                    | Solution                                    |
| --------------------- | -------------------------- | ------------------------------------------- |
| `invalid_credentials` | Missing or invalid API key | Include `X-Api-Key` header with a valid key |

```json theme={null}
{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}
```

## Validation Errors (400)

### Message Endpoints

| Code                | Message                                                 | Solution                       |
| ------------------- | ------------------------------------------------------- | ------------------------------ |
| `missing_to`        | Recipient phone number (to\_msisdn) is required         | Provide the `to_msisdn` field  |
| `missing_body`      | Message body is required                                | Provide the `body` field       |
| `missing_from`      | Sending number ID (from\_phone\_number\_id) is required | Provide `from_phone_number_id` |
| `invalid_phone`     | Invalid phone number format                             | Use E.164 format (+1...)       |
| `too_many_messages` | Maximum 1000 messages per request                       | Split into smaller batches     |
| `missing_messages`  | Messages array is required                              | Provide the `messages` array   |

### Example: Missing Field

```json theme={null}
{
  "error": "Recipient phone number (to_msisdn) is required",
  "code": "missing_to"
}
```

### Example: Invalid Phone

```json theme={null}
{
  "error": "Invalid phone number format",
  "code": "invalid_phone"
}
```

## Resource Errors (404)

| Code             | Message                  | Solution                                               |
| ---------------- | ------------------------ | ------------------------------------------------------ |
| `list_not_found` | Sending number not found | Verify the `from_phone_number_id` exists and is active |

```json theme={null}
{
  "error": "Sending number not found",
  "code": "list_not_found"
}
```

## Handling Errors

### Python Example

```python theme={null}
import requests

response = requests.post(
    "https://api.tracklysms.com/api/v1/messages",
    headers={"X-Api-Key": "your_key", "Content-Type": "application/json"},
    json={"to": "+14155551234", "body": "Hello", "from_phone_number_id": "pn_123"}
)

if response.status_code == 201:
    result = response.json()
    print(f"Message queued: {result['message_id']}")
elif response.status_code == 401:
    print("Authentication failed - check your API key")
elif response.status_code == 400:
    error = response.json()
    print(f"Validation error: {error['error']} (code: {error['code']})")
elif response.status_code == 404:
    print("Resource not found - check your from_phone_number_id")
else:
    print(f"Unexpected error: {response.status_code}")
```

### JavaScript Example

```javascript theme={null}
try {
  const response = await axios.post(
    'https://api.tracklysms.com/api/v1/messages',
    { to: '+14155551234', body: 'Hello', from_phone_number_id: 'pn_123' },
    { headers: { 'X-Api-Key': 'your_key' } }
  );

  console.log('Message queued:', response.data.message_id);
} catch (error) {
  if (error.response) {
    const { status, data } = error.response;

    switch (status) {
      case 401:
        console.error('Authentication failed');
        break;
      case 400:
        console.error(`Validation error: ${data.error}`);
        break;
      case 404:
        console.error('Resource not found');
        break;
      default:
        console.error(`Error ${status}: ${data.error}`);
    }
  }
}
```

## Deprecation Headers

All v1 API responses include deprecation headers:

```http theme={null}
X-API-Deprecated: v1 is deprecated
Deprecation: true
```

These headers indicate the API version is deprecated. Watch for announcements about the v2 API.

## API Limits

Trackly SMS rate-limits API requests to **60 per minute per IP address** (`429 rate_limited`). For the full rate-limit, payload-size, and bulk-batch guidance, see [API Limits & Best Practices](/api-reference/v2/rate-limiting).

## Getting Help

If you encounter persistent errors:

<CardGroup cols={2}>
  <Card title="Discord Support" icon="discord" href="https://discord.gg/tracklysms">
    Create a support ticket with `/support new`
  </Card>

  <Card title="FAQ" icon="circle-question" href="/resources/faq">
    Check common questions
  </Card>
</CardGroup>