{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The 'to' field must be a valid E.164 phone number",
    "status": 422,
    "details": {
      "field": "to",
      "value": "+1234",
      "expected": "E.164 format e.g. +14155552671"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-08T00:00:00Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_PHONE_NUMBER"
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "1234", "body": "Hello"}'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid SMS payload",
    "status": 422,
    "details": {
      "issues": [
        { "field": "to", "message": "Must be a valid E.164 phone number" }
      ]
    }
  },
  "meta": {
    "request_id": "req_1234",
    "timestamp": "2026-05-10T12:00:00Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/VALIDATION_ERROR"
  }
}

import { Orbit, OrbitApiError } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY })

// Branch on error.code first — only some failures are retriable.
function classify(error: OrbitApiError) {
  // 429 / 5xx are retriable; 4xx terminal errors (INVALID_PHONE_NUMBER,
  // REAUTH_REQUIRED, ...) must not be re-sent.
  const retriable = error.status >= 500 || error.status === 429
  const retryAfterMs = error.details?.retry_after // seconds
  return { retriable, retryAfterMs: retryAfterMs ? retryAfterMs * 1000 : 0 }
}

for (let attempt = 0; attempt < 3; attempt++) {
  try {
    await orbit.messages.send({ channel: 'sms', to: '+14155552671', body: 'Hi' })
    break
  } catch (error) {
    if (error instanceof OrbitApiError) {
      const { retriable, retryAfterMs } = classify(error)
      // Log the envelope fields up front — request_id goes into the
      // structured log so a support ticket can pinpoint the failure.
      console.error({
        code: error.code,
        status: error.status,
        requestId: error.requestId,
        attempt,
      })
      if (!retriable) throw error
      // Honor Retry-After when the server says so; otherwise
      // exponential backoff.
      await new Promise((resolve) =>
        setTimeout(resolve, retryAfterMs || 2 ** attempt * 1000)
      )
    } else {
      throw error
    }
  }
}

import logging
import os
import time

from orbit_sdk import OrbitClient, OrbitError

logger = logging.getLogger(__name__)

client = OrbitClient(api_key=os.environ["ORBIT_API_KEY"])

for attempt in range(3):
    try:
        client.messages.send_sms(to="+14155552671", body="Hi")
        break
    except OrbitError as e:
        # Capture the envelope fields in the structured log entry now —
        # request_id is the key support uses to trace the request.
        logger.error(
            "orbit.send_sms failed",
            extra={
                "code": e.code,
                "status": e.status,
                "request_id": e.request_id,
                "attempt": attempt,
            },
        )
        # 429 / 5xx are retriable; 4xx terminal errors (e.g.
        # INVALID_PHONE_NUMBER) must not be re-sent.
        retriable = e.status is not None and (e.status >= 500 or e.status == 429)
        if not retriable:
            raise
        # Honor the SDK's parsed retry_after (seconds) when present;
        # otherwise exponential backoff.
        retry_after = getattr(e, "retry_after", None)
        time.sleep(retry_after if retry_after is not None else 2 ** attempt)

import (
  "errors"
  "log"

  "github.com/devotel/orbit-go/orbit"
)

client, _ := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
for attempt := 0; attempt < 3; attempt++ {
  _, err := client.Messages().SendSMS(ctx, orbit.SendSMSInput{
    To: "+14155552671", Body: "Hi",
  })
  var apiErr *orbit.Error
  if !errors.As(err, &apiErr) {
    break
  }
  // Log the envelope fields before deciding — RequestID is the key
  // support uses to trace the request.
  log.Printf("kind=%s code=%s status=%d request=%s attempt=%d",
    apiErr.Kind, apiErr.Code, apiErr.StatusCode,
    apiErr.RequestID, attempt)
  // KindServer / KindRateLimit are retriable; KindClient /
  // KindAuthentication are terminal.
  retriable := apiErr.Kind == orbit.KindServer ||
    apiErr.Kind == orbit.KindRateLimit
  if !retriable {
    break
  }
  // Honor the server-supplied RetryAfter when present; otherwise
  // exponential backoff.
  if apiErr.RetryAfter > 0 {
    time.Sleep(apiErr.RetryAfter)
  } else {
    time.Sleep(time.Duration(1<<attempt) * time.Second)
  }
}

client.request("POST", "/messages",
    null,
    Map.of("channel", "sms", "to", "+14155552671", "body", "Hi"),
    null);

await client.RequestAsync("POST", "/messages",
    body: new { channel = "sms", to = "+14155552671", body = "Hi" });

$client->request('POST', '/messages', null, [
    'channel' => 'sms',
    'to' => '+14155552671',
    'body' => 'Hi',
]);

client.request("POST", "/messages",
    body: { channel: "sms", to: "+14155552671", body: "Hi" })