# Understanding Responses
URL: /docs/getting-started/understanding-responses

> Complete guide to SMS Pro API response envelopes, RFC 7807 error formats, HTTP status codes, rate limits, and retry strategies.

The SMS Pro API adheres to consistent, predictable JSON conventions across all endpoints. Every HTTP response is structured using standardized envelopes for both successful transactions and error conditions.

---

## 1. Successful Response Envelope [#1-successful-response-envelope]

All successful responses (`2xx` status codes) return the standard `ResourceResponse<T>` envelope:

```json
{
  "status": "success",
  "message": "Human-readable summary of the operation",
  "data": { ... }
}
```

### Key Envelope Fields [#key-envelope-fields]
- **`status`** *(string)*: Always `"success"`.
- **`message`** *(string)*: A concise summary of the outcome (e.g. `"Queued"`, `"Balance retrieved"`, `"Sender ID verified"`).
- **`data`** *(object | array)*: The requested resource object or array of items.

---

## 2. Error Response Envelope (RFC 7807) [#2-error-response-envelope-rfc-7807]

When an API call fails (`4xx` or `5xx` status codes), the gateway returns an **RFC 7807 Problem Details** document with `Content-Type: application/problem+json`:

```json
{
  "type": "https://docs.smspro.com/errors/insufficient-credits",
  "title": "INSUFFICIENT CREDITS",
  "status": 402,
  "detail": "Insufficient credits for this send.",
  "instance": "/api/v1/public/sms/send",
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits for this send.",
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}
```

### Error Envelope Fields Explained [#error-envelope-fields-explained]
- **`type`** *(URI)*: A stable link referencing the error documentation.
- **`title`** *(string)*: A short, human-readable summary of the problem type.
- **`status`** *(number)*: The HTTP status code generated by the origin server.
- **`detail`** *(string)*: An explanation of the exact occurrence to assist in debugging.
- **`code`** *(string)*: A machine-readable application error code, such as `INSUFFICIENT_CREDITS`.
- **`requestId`** *(string)*: A unique correlation ID. Always supply this value when opening a support ticket with the SMS Pro engineering team.
- **`invalidParams`** *(array, optional)*: Present on `400 Bad Request` validation failures, detailing which fields failed schema checks:
  ```json
  "invalidParams": [
    {
      "name": "to",
      "reason": "For local Ghana numbers starting with 0, exactly 10 digits are required (e.g. 0241234567)."
    }
  ]
  ```

---

## 3. HTTP Status Codes Reference [#3-http-status-codes-reference]

SMS Pro uses standard HTTP response codes to indicate the success or failure of an API request:

| Status Code | Meaning | Typical Scenario |
| :--- | :--- | :--- |
| **`200 OK`** | Success | `GET` requests (balance query, message status lookup) or synchronous `PUT`/`PATCH` updates. |
| **`201 Created`** | Created | Resource was created (e.g. creating a new shortlink or MFA policy). |
| **`202 Accepted`** | Queued | Asynchronous dispatch accepted. Message has entered the telco delivery pipeline. |
| **`400 Bad Request`** | Validation Error | Malformed JSON, missing required fields, or invalid E.164 phone numbers. |
| **`401 Unauthorized`** | Authentication Failure | Missing or invalid API key. An address outside an IP whitelist is also rejected as an invalid key. |
| **`402 Payment Required`** | Wallet Depleted | Insufficient prepaid SMS units or wallet balance to route the message. |
| **`403 Forbidden`** | Scope Failure | API key lacks the required scope (`FORBIDDEN_SCOPE`). |
| **`404 Not Found`** | Missing Resource | Requested message ID, job ID, or survey does not exist. |
| **`409 Conflict`** | Resource Conflict | Duplicate resource submission or concurrent modification lock. |
| **`422 Unprocessable`** | Semantic Error | Valid syntax, but a business rule failed. Key allocation uses `API_KEY_ALLOCATION_EXCEEDED`. |
| **`429 Too Many Requests`**| Rate Limited | Exceeded per-minute request threshold. Back off and retry. |
| **`500 Internal Error`** | Server Error | Unexpected failure. Retry the request with the same idempotency key. |
| **`503 Unavailable`** | Temporarily unavailable | Retry later. |

---

## 4. Application Error Codes [#4-application-error-codes]

When parsing errors programmatically, branch on the `code` property rather than parsing human-readable `detail` strings:

| Application Error Code | HTTP Status | Recommended Action |
| :--- | :--- | :--- |
| `UNAUTHORIZED` | 401 | The key is missing, unknown, or the caller is outside the IP whitelist. |
| `FORBIDDEN_SCOPE` | 403 | Add the missing scope, such as `sms:send`, on the key. |
| `API_KEY_ALLOCATION_EXCEEDED` | 422 | Raise the key's SMS allocation, or use another key. |
| `INVALID_PHONE_NUMBER` | 422 | The recipient is empty or not a usable number. |
| `INVALID_PHONE` | 422 | OTP and similar routes use this code for a missing or unusable number. |
| `DESTINATION_COUNTRY_NOT_SUPPORTED` | 422 | The destination country is not enabled for the account. |
| `INSUFFICIENT_CREDITS` | 402 | Add credit from Wallet, then retry with the same idempotency key. |
| `RATE_LIMIT_EXCEEDED` | 429 | Wait, then retry with the same idempotency key. |
| `TOO_MANY_REQUESTS` | 429 | Wait, then retry with the same idempotency key. |

---

## 5. Rate Limits & Headers [#5-rate-limits--headers]

Every API response from the public SMS routes includes these headers:

| Response Header | Description |
| :--- | :--- |
| `X-RateLimit-Limit` | Maximum number of requests allowed in the current 60-second window. |
| `X-RateLimit-Remaining` | Number of remaining calls available before hitting the rate limit. |
| `X-RateLimit-Reset` | Seconds left in the current one-minute window. |
| `Retry-After` | Present on `429` responses; number of seconds to wait before retrying. |

---

## 6. Recommended Retry Strategy [#6-recommended-retry-strategy]

When receiving transient errors (`429 Too Many Requests`, `500 Internal Server Error`, or `503 Service Unavailable`), follow an **exponential backoff with jitter** strategy:

1. **Check `Retry-After` Header**: If a `429` response provides a `Retry-After` header, wait for that duration before retrying.
2. **Preserve the `Idempotency-Key`**: Always send the exact same `Idempotency-Key` header on all retries. This ensures the SMS is never dispatched twice if the initial request succeeded behind a gateway timeout.
3. **Exponential Backoff Formula**: For network timeouts, compute sleep intervals using:
   ```text
   wait_time = min(max_backoff, base_backoff * (2 ^ attempt)) ± jitter
   ```
4. **Never Retry 4xx Client Errors**: Never retry `400`, `401`, `402`, or `422` without altering the request payload or credentials, as these are permanent validation or authorization failures.

---

## Next Step [#next-step]

Explore mock telco testing, magic numbers, and delivery receipts in [Testing in Sandbox](/docs/getting-started/testing-in-sandbox).