API Error Codes

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The provided phone number is invalid",
    "field": "to",
    "documentation_url": "https://smsroute.cc/errors"
  }
}

HTTP Status Codes

Every API response includes an HTTP status code that indicates the broad category of the result. Successful requests return 200 OK. Errors return one of the codes below.

Error Codes

The code field in the error response body provides a machine-readable identifier for the specific problem. Use it in your error-handling logic to branch on the failure mode.

Error Response Fields

Handling Errors in Production

Retry Logic

For 429 (rate limit) and 5xx (server error) responses, implement retry logic with exponential backoff. Respect the Retry-After header when present — it tells you exactly how many seconds to wait.

import time

def send_sms_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, headers=headers, timeout=10)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.Timeout:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                # Rate limited — wait and retry
                time.sleep(60)
                continue
            elif e.response.status_code >= 500:
                # Server error — retry
                if attempt < max_retries - 1:
                    time.sleep(5)
                    continue
            raise  # 4xx errors are not retryable

Webhook Delivery Receipts

For asynchronous delivery status, provide a callback_url when sending SMS. SMSRoute will POST delivery receipts to your endpoint as messages transition through queued → sent → delivered or failed. Acknowledge webhooks with 200 OK to prevent retries.

Idempotency Keys

Pass an Idempotency-Key header on POST requests. If the same key is used within 24 hours, the API returns the original response without duplicating the operation. This lets you safely retry on network errors without risk of double-sending.

Related Resources