Errors worth branching on

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Transactional US",
    "sender_pool_id": "pool_us_nanpa",
    "opt_out_list_id": "optout_default",
    "mps_cap": 50
  }'

{
  "data": {
    "id": "msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC",
    "label": "Transactional US",
    "sender_pool_id": "pool_us_nanpa",
    "country_sender_pools": {},
    "opt_out_list_id": "optout_default",
    "inbound_webhook_url": null,
    "inbound_method": "POST",
    "fallback_url": null,
    "status_callback": null,
    "sticky_sender": false,
    "area_code_geomatch": false,
    "mms_converter": false,
    "smart_encoding": false,
    "validity_period_seconds": null,
    "mps_cap": 50,
    "external_id": null,
    "feature_flags": {},
    "created_at": "2026-09-03T12:00:00.000Z",
    "updated_at": "2026-09-03T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_msgcreate01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Transactional US",
    "sender_pool_id": "pool_us_nanpa",
    "opt_out_list_id": "optout_default",
    "mps_cap": 50
  }'

{
  "data": {
    "id": "msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC",
    "label": "Transactional US",
    "sender_pool_id": "pool_us_nanpa",
    "country_sender_pools": {},
    "opt_out_list_id": "optout_default",
    "inbound_webhook_url": null,
    "inbound_method": "POST",
    "fallback_url": null,
    "status_callback": null,
    "sticky_sender": false,
    "area_code_geomatch": false,
    "mms_converter": false,
    "smart_encoding": false,
    "validity_period_seconds": null,
    "mps_cap": 50,
    "external_id": null,
    "feature_flags": {},
    "created_at": "2026-09-03T12:00:00.000Z",
    "updated_at": "2026-09-03T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_msgcreate01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

Worked request and response samples

A messaging service is the container /v1/messages resolves once at send time — sender pool, opt-out list, inbound webhook, sending flags and throughput cap under one id you pass as messaging_service_id. Only label is required at create; every other field is nullable. The four-step loop below is the whole journey: make the container, bind two senders, verify the residency pin, then check the per-service throughput gate before arming an outbound campaign. Channel-fallback equivalents of this exact loop are in SMS services and the Messaging Services console guide.

1. Create the container

POST /api/v1/messaging/services

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Transactional US",
    "sender_pool_id": "pool_us_nanpa",
    "opt_out_list_id": "optout_default",
    "mps_cap": 50
  }'

{
  "data": {
    "id": "msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC",
    "label": "Transactional US",
    "sender_pool_id": "pool_us_nanpa",
    "country_sender_pools": {},
    "opt_out_list_id": "optout_default",
    "inbound_webhook_url": null,
    "inbound_method": "POST",
    "fallback_url": null,
    "status_callback": null,
    "sticky_sender": false,
    "area_code_geomatch": false,
    "mms_converter": false,
    "smart_encoding": false,
    "validity_period_seconds": null,
    "mps_cap": 50,
    "external_id": null,
    "feature_flags": {},
    "created_at": "2026-09-03T12:00:00.000Z",
    "updated_at": "2026-09-03T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_msgcreate01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

Nullable fields you omit stay unset; a null on a later PATCH clears them. external_id is only for migrator import (Twilio MGxxx) and must be unique — a duplicate returns 409 (see the 409 block below).

2. Bind two senders

POST /api/v1/messaging/services/{id}/phone-numbers

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services/msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC/phone-numbers \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "num_did_01HF77QZK2M9P2R5T8VXYNBJ" }'

{
  "data": {
    "messaging_service_id": "msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC",
    "phone_number_id": "num_did_01HF77QZK2M9P2R5T8VXYNBJ",
    "phone_number": "+14155552671",
    "country_code": "US",
    "capabilities": ["sms", "mms", "voice"],
    "attached_at": "2026-09-03T12:00:01.000Z"
  },
  "meta": {
    "request_id": "req_msgattach01",
    "timestamp": "2026-09-03T12:00:01Z"
  }
}

Run this twice with two different DIDs so the pool has redundancy; reattach of the same pair is idempotent (same envelope, no error). The DID must belong to the tenant and be SMS-capable — a voice/fax/MMS-only DID is rejected with 422. Detach later via DELETE /api/v1/messaging/services/{id}/phone-numbers/{numberId} (204, no body).

3. Verify the residency pin

Before arming a campaign for a regulated buyer, confirm where the message plane rests and is processed.

GET /api/v1/messaging/data-residency

curl -X GET https://api.orbit.devotel.io/api/v1/messaging/data-residency \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

{
  "data": {
    "pinnedRegion": "eu",
    "enforced": true,
    "plane": {
      "plane": "messaging",
      "label": "Messaging (SMS, MMS, chat) bodies & metadata",
      "storageClass": "primary_database",
      "residencyScoped": true,
      "residentRegion": "eu",
      "processingScoped": true,
      "processedRegion": "eu",
      "note": "Stored in the European Union; processing follows the platform compute region."
    },
    "supportedRegions": [
      {
        "region": "eu",
        "label": "European Union",
        "jurisdictions": ["AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE"],
        "frameworks": ["GDPR"],
        "storageLocation": "eu",
        "apiRegion": "eu",
        "availability": "available"
      },
      {
        "region": "us",
        "label": "United States",
        "jurisdictions": ["US"],
        "frameworks": ["CCPA", "HIPAA"],
        "storageLocation": "us",
        "apiRegion": "us",
        "availability": "preview"
      }
    ],
    "storedAndProcessedInRegion": true,
    "api_region": {
      "apiRegion": "eu",
      "targetApiRegion": "eu",
      "inRegion": true,
      "targetApiEndpoint": "https://api.eu.orbit.devotel.io/api/v1",
      "targetApiEndpointLive": true
    }
  },
  "meta": {
    "request_id": "req_msgres01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

storedAndProcessedInRegion: true is the whole answer — both the at-rest and the processing axes of the plane honour the pin. When it reports false, route the campaign through BYOC or hold it. This is a tenant-owned control; it wires no carrier and changes nothing about how traffic terminates.

4. Check the throughput gate, then send

Before arming a campaign, read the per-service gate live and re-arm only when the queue is clear.

GET /api/v1/messaging/services/{id}/throughput-stats

curl -X GET https://api.orbit.devotel.io/api/v1/messaging/services/msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC/throughput-stats \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

{
  "data": {
    "service_sid": "msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC",
    "label": "Transactional US",
    "mps_cap": 50,
    "window_second": 1789982400,
    "demand": 63,
    "current_mps": 50,
    "queue_depth": 13,
    "utilization_pct": 100,
    "recent_throttle_count": 13,
    "trailing_throttle_count": 41,
    "last_throttle_at": 1789982399702
  },
  "meta": {
    "request_id": "req_msgstat01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

mps_cap is null when the service is uncapped; queue_depth counts over-cap sends 429’d this second. Raise or clear the cap with PATCH /api/v1/messaging/services/{id}/throughput ({ "mps_cap": 80 } or null). The frequency caps guide covers recipient-level pacing; message suppression handles opt-outs — both compose into the same gate. These five failures cover the messaging-service create (POST /api/v1/messaging-services), which campaign provisioning flows through. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_messagina1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_messagina1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "name", "value": "Support Line_1", "expected": "1-48 chars, no trailing underscores" }
    },
    "meta": {
      "request_id": "req_messaginb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with an allowed service name (1-48 chars) instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_messaginc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

409 — Conflict

  {
    "error": {
      "code": "MESSAGING_SERVICE_SENDER_CONFLICT",
      "message": "This sender is already bound to another messaging service.",
      "status": 409,
      "details": { "sender": "+14155552671", "bound_service_id": "msg-svc_01HF7ZQ3K4M9P2R5T8VXYNBC" }
    },
    "meta": {
      "request_id": "req_messagind4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Detach via the existing service first, then POST again — the sender mapping is single-owner.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`MESSAGING_SERVICE_SENDER_CONFLICT` (409 conflict)	Detach via the existing service first, then POST again	Branch on `error.code`. The sender mapping is single-owner.

API Reference

All Endpoints

Worked request and response samples

1. Create the container

2. Bind two senders

3. Verify the residency pin

4. Check the throughput gate, then send

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

60-second retry matrix

​Worked request and response samples

​1. Create the container

​2. Bind two senders

​3. Verify the residency pin

​4. Check the throughput gate, then send

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​409 — Conflict

​60-second retry matrix

Worked request and response samples

1. Create the container

2. Bind two senders

3. Verify the residency pin

4. Check the throughput gate, then send

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

60-second retry matrix