# API Reference Overview
URL: /docs/api-reference

> Base URLs, ResourceResponse envelopes, rate limit headers, and RFC 7807 Problem Details for the SMS Pro v1/v2 API.

The SMS Pro Developer API follows RESTful JSON conventions over HTTPS with an interactive OpenAPI 3.1 playground on every operation page.

## API and keys [#api-and-keys]

Every call uses `https://api.smspro.com`.

| Key prefix | Behavior |
| :--- | :--- |
| `sk_test_` | Simulated delivery. No wallet charge. Magic numbers select a specific outcome. |
| `sk_live_` | Carrier delivery. Uses wallet credit. |

Pass the key with `X-Api-Key` or `Authorization: Bearer`.

## Standard Success Envelope [#standard-success-envelope]

All JSON endpoints wrap response payloads inside a uniform `ResourceResponse` envelope:

```json
{
  "status": "success",
  "message": "Operation completed successfully",
  "data": {
    "balance": 250.0,
    "smsUnits": 1000,
    "currency": "GHS"
  }
}
```

## Rate Limit & Tracing Headers [#rate-limit--tracing-headers]

Responses include diagnostic and rate-limiting metadata headers:

<TypeTable type={{"X-Request-Id":{"description":"Unique request tracing identifier for support and log correlation.","type":"string"},"X-RateLimit-Limit":{"description":"Maximum requests permitted per rolling 60-second window.","type":"integer"},"X-RateLimit-Remaining":{"description":"Requests remaining in the active window.","type":"integer"},"X-RateLimit-Reset":{"description":"Seconds remaining until the rate-limit bucket resets.","type":"integer"}}} />

## RFC 7807 Problem Details Errors [#rfc-7807-problem-details-errors]

Non-2xx responses return `Content-Type: application/problem+json` following RFC 7807:

```json
{
  "type": "https://docs.smspro.com/errors/insufficient-credits",
  "title": "Insufficient Unit Credits",
  "status": 422,
  "detail": "Wallet PAYG balance or SMS credit units insufficient for carrier dispatch.",
  "instance": "/api/v1/public/sms/send",
  "code": "INSUFFICIENT_CREDITS",
  "requestId": "d50c1f10-982f-4889-8d76-d392ef401032"
}
```

| HTTP Status | Typical Causes |
| :--- | :--- |
| `400 Bad Request` | Malformed JSON body or missing required field |
| `401 Unauthorized` | Missing, revoked, or malformed `X-Api-Key` / `Bearer` token |
| `403 Forbidden` | Key lacks required permission scope (for example `sms:send` or `mfa:write`) |
| `404 Not Found` | Resource ID (`messageId`, `batchId`, `otpId`, or `challengeId`) does not exist |
| `422 Unprocessable Entity` | Invalid E.164 recipient, >10 transactional recipients, or `INSUFFICIENT_CREDITS` |
| `429 Too Many Requests` | Rate limit exceeded; inspect `X-RateLimit-Reset` before retrying |