Skip to Content

Understanding Responses

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

View Markdown (.md)

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 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:
    "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 CodeMeaningTypical Scenario
200 OKSuccessGET requests (balance query, message status lookup) or synchronous PUT/PATCH updates.
201 CreatedCreatedResource was created (e.g. creating a new shortlink or MFA policy).
202 AcceptedQueuedAsynchronous dispatch accepted. Message has entered the telco delivery pipeline.
400 Bad RequestValidation ErrorMalformed JSON, missing required fields, or invalid E.164 phone numbers.
401 UnauthorizedAuthentication FailureMissing or invalid API key. An address outside an IP whitelist is also rejected as an invalid key.
402 Payment RequiredWallet DepletedInsufficient prepaid SMS units or wallet balance to route the message.
403 ForbiddenScope FailureAPI key lacks the required scope (FORBIDDEN_SCOPE).
404 Not FoundMissing ResourceRequested message ID, job ID, or survey does not exist.
409 ConflictResource ConflictDuplicate resource submission or concurrent modification lock.
422 UnprocessableSemantic ErrorValid syntax, but a business rule failed. Key allocation uses API_KEY_ALLOCATION_EXCEEDED.
429 Too Many RequestsRate LimitedExceeded per-minute request threshold. Back off and retry.
500 Internal ErrorServer ErrorUnexpected failure. Retry the request with the same idempotency key.
503 UnavailableTemporarily unavailableRetry later.

4. Application Error Codes

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

Application Error CodeHTTP StatusRecommended Action
UNAUTHORIZED401The key is missing, unknown, or the caller is outside the IP whitelist.
FORBIDDEN_SCOPE403Add the missing scope, such as sms:send, on the key.
API_KEY_ALLOCATION_EXCEEDED422Raise the key's SMS allocation, or use another key.
INVALID_PHONE_NUMBER422The recipient is empty or not a usable number.
INVALID_PHONE422OTP and similar routes use this code for a missing or unusable number.
DESTINATION_COUNTRY_NOT_SUPPORTED422The destination country is not enabled for the account.
INSUFFICIENT_CREDITS402Add credit from Wallet, then retry with the same idempotency key.
RATE_LIMIT_EXCEEDED429Wait, then retry with the same idempotency key.
TOO_MANY_REQUESTS429Wait, then retry with the same idempotency key.

5. Rate Limits & Headers

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

Response HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the current 60-second window.
X-RateLimit-RemainingNumber of remaining calls available before hitting the rate limit.
X-RateLimit-ResetSeconds left in the current one-minute window.
Retry-AfterPresent on 429 responses; number of seconds to wait before retrying.

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:
    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

Explore mock telco testing, magic numbers, and delivery receipts in Testing in Sandbox.

On this page