{
  "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"
  }
}

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) {
  // 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)
  }
}

// Any HTTP client works — here, plain fetch, reading each envelope field
// and honoring the server-supplied pacing.
const response = await fetch('https://api.orbit.devotel.io/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORBIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channel: 'sms', to: '+14155552671', body: 'Hi' }),
})

if (response.ok) {
  const { data } = await response.json()
} else {
  const body = await response.json()
  const { error, meta } = body
  // Log the code + request_id as one structured entry — meta.request_id
  // is the key support uses to trace the request.
  console.error({ code: error.code, requestId: meta.request_id, status: response.status })

  // Branch on error.code/status before retrying: 429 (and the
  // RATE_LIMITED / RATE_LIMIT_EXCEEDED family) is retriable — honor
  // error.details.retry_after (seconds) or the Retry-After header.
  // 422 terminal codes (INVALID_PHONE_NUMBER and friends) must NOT be
  // retried — re-sending a validation failure makes things worse.
  const retriable = response.status === 429 || response.status >= 500
  if (retriable) {
    const retryAfterSeconds =
      error.details?.retry_after ??
      Number(response.headers.get('Retry-After') ?? 1)
    await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000))
  }
}