# Error Handling & Diagnostics
URL: /docs/guides/error-handling-and-troubleshooting

> Comprehensive technical troubleshooting guide covering RFC 7807 error taxonomy, carrier failure diagnostics, and request tracing.

When integrating telecommunication services, distinguishing between **API-layer failures** (e.g. invalid authentication or schema violations) and **telecom-layer failures** (e.g. handset out of coverage or spam filtering) is critical to diagnosing issues quickly.

---

## 1. Error Taxonomy & Layering [#1-error-taxonomy--layering]

Errors in SMS Pro originate at three distinct architectural tiers:

![Error Tiers Taxonomy](/images/error-tiers-taxonomy.svg)

---

## 2. RFC 7807 Problem Details Format [#2-rfc-7807-problem-details-format]

All synchronous API errors return structured JSON using the RFC 7807 `application/problem+json` standard:

```json
{
  "type": "https://docs.smspro.com/errors/invalid-phone",
  "title": "Invalid Recipient Phone Number",
  "status": 400,
  "detail": "For local Ghana numbers starting with 0, exactly 10 digits are required (e.g. 0241234567). Given: 024123",
  "code": "INVALID_PHONE_NUMBER",
  "instance": "/api/v1/public/sms/send",
  "requestId": "req-9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "timestamp": "2026-11-18T09:15:00Z"
}
```

### Essential Diagnostic Fields [#essential-diagnostic-fields]
- **`code`**: A stable, machine-readable enum. Write application branching logic against `code`, never by parsing `detail` strings.
- **`requestId`**: The unique trace ID generated at the gateway edge. Quote this ID when submitting support tickets or searching console logs.
- **`invalidParams`**: A detailed array identifying specific field validation errors on `400` responses.

---

## 3. Comprehensive Application Error Codes [#3-comprehensive-application-error-codes]

| Application Code | HTTP Status | Root Cause | Resolution |
| :--- | :--- | :--- | :--- |
| **`UNAUTHORIZED`** | `401` | The key is missing, unknown, or the caller is outside the IP whitelist. | Check the key and the whitelist. |
| **`FORBIDDEN_SCOPE`** | `403` | The key lacks the required scope. | Edit scopes under **Developer > API Keys**. |
| **`API_KEY_ALLOCATION_EXCEEDED`** | `422` | The key has used its SMS allocation. | Raise the allocation or use another key. |
| **`INVALID_PHONE`** | `422` | The phone number is missing or not a usable number. | Send a local or international number SMS Pro can clean. |
| **`RATE_LIMIT_EXCEEDED`** | `429` | The key is over its per-minute limit. | Wait for `Retry-After`, then retry with the same idempotency key. |

---

## 4. Diagnosing Common Integration Anomalies [#4-diagnosing-common-integration-anomalies]

### Anomaly 1: "Subscribers are receiving duplicate text messages" [#anomaly-1-subscribers-are-receiving-duplicate-text-messages]
- **Cause**: Your application is timing out waiting for an HTTP response, catching an error, and retrying the request **without** an `Idempotency-Key`. The initial request succeeded on the gateway, and the retry sent a second message.
- **Fix**: Always generate a unique `Idempotency-Key` (UUID v4) for each logical message. When retrying network drops, send the **same** key. SMS Pro will return the cached response rather than queueing a second message.

### Anomaly 2: "Messages report `SENT`, but no Delivery Report arrives" [#anomaly-2-messages-report-sent-but-no-delivery-report-arrives]
- **Cause**: The subscriber's handset is powered off, out of signal range, or roaming on a network with delayed DLR forwarding.
- **Fix**: Check `GET /api/v1/public/sms/messages/{messageId}`. If the message remains in `SENT`, the carrier SMSC is still attempting delivery within its 24-hour validity window.

### Anomaly 3: "A 160-character message was billed as 3 units" [#anomaly-3-a-160-character-message-was-billed-as-3-units]
- **Cause**: An invisible Unicode character (such as an emoji, non-breaking space, or curly apostrophe `’`) forced the message into **UCS-2 encoding**, reducing the capacity to 70 characters per segment.
- **Fix**: Run dynamic text through a GSM-7 sanitizer or inspect the `segmentCount` in the `202 Accepted` response.

---

## Related Documentation [#related-documentation]
- 📖 [Delivery Reports (DLR) Deep Dive](/docs/guides/delivery-reports-dlr)
- 📖 [Architecture, Resiliency & Scale](/docs/guides/architecture-and-resilience)
- ⚡ [Recipe: Idempotent SMS Dispatch](/docs/recipes/idempotent-sms-dispatch)