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
All successful responses (2xx status codes) return the standard ResourceResponse<T> envelope:
{
"status": "success",
"message": "Human-readable summary of the operation",
"data": { ... }
}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)
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:
{
"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
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 asINSUFFICIENT_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 on400 Bad Requestvalidation failures, detailing which fields failed schema checks:"invalidParams": [ { "name": "to", "reason": "For local Ghana numbers starting with 0, exactly 10 digits are required (e.g. 0241234567)." } ]
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
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
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
When receiving transient errors (429 Too Many Requests, 500 Internal Server Error, or 503 Service Unavailable), follow an exponential backoff with jitter strategy:
- Check
Retry-AfterHeader: If a429response provides aRetry-Afterheader, wait for that duration before retrying. - Preserve the
Idempotency-Key: Always send the exact sameIdempotency-Keyheader on all retries. This ensures the SMS is never dispatched twice if the initial request succeeded behind a gateway timeout. - Exponential Backoff Formula: For network timeouts, compute sleep intervals using:
wait_time = min(max_backoff, base_backoff * (2 ^ attempt)) ± jitter - Never Retry 4xx Client Errors: Never retry
400,401,402, or422without altering the request payload or credentials, as these are permanent validation or authorization failures.
Next Step
Explore mock telco testing, magic numbers, and delivery receipts in Testing in Sandbox.