Errors worth branching on

curl -X POST "https://api.orbit.devotel.io/api/v1/messaging/sender-pools" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "US support rotation",
    "sender_dids": ["+14155550100", "+14155550101"],
    "strategy": "sticky"
  }'

{
  "data": {
    "id": "pool_9w7x4c8a2e6d9b1f7305abcd",
    "label": "US support rotation",
    "sender_dids": ["+14155550100", "+14155550101"],
    "strategy": "sticky",
    "created_at": "2026-09-14T12:00:00.000Z",
    "updated_at": "2026-09-14T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_pool_create",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

curl -X POST "https://api.orbit.devotel.io/api/v1/messaging/sender-pools" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "US support rotation",
    "sender_dids": ["+14155550100", "+14155550101"],
    "strategy": "sticky"
  }'

{
  "data": {
    "id": "pool_9w7x4c8a2e6d9b1f7305abcd",
    "label": "US support rotation",
    "sender_dids": ["+14155550100", "+14155550101"],
    "strategy": "sticky",
    "created_at": "2026-09-14T12:00:00.000Z",
    "updated_at": "2026-09-14T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_pool_create",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Worked request and response samples

Copy a request as written, substitute your own ids, and compare the response envelope. The chain a pool-integration runs: create → list → send through the pool → (optional) preview → swap strategy. For narrative walkthroughs see the Sender pools guide.

1. Create a pool

POST /api/v1/messaging/sender-pools

Request

curl -X POST "https://api.orbit.devotel.io/api/v1/messaging/sender-pools" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "US support rotation",
    "sender_dids": ["+14155550100", "+14155550101"],
    "strategy": "sticky"
  }'

sender_dids accepts a mix of E.164 long codes, numeric short codes, and alphanumeric sender IDs (up to 50 per pool, no duplicates). Success returns 201 with the new pool id:

{
  "data": {
    "id": "pool_9w7x4c8a2e6d9b1f7305abcd",
    "label": "US support rotation",
    "sender_dids": ["+14155550100", "+14155550101"],
    "strategy": "sticky",
    "created_at": "2026-09-14T12:00:00.000Z",
    "updated_at": "2026-09-14T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_pool_create",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

2. List pools

GET /api/v1/messaging/sender-pools

Request

curl "https://api.orbit.devotel.io/api/v1/messaging/sender-pools?limit=25" \
  -H "X-API-Key: dv_live_sk_your_key_here"

The list is keyset-paginated: limit is clamped to 1–100 (default 50) and meta.pagination carries has_more plus the opaque next_cursor to pass back as ?cursor=.... Each row includes the full sender_dids membership:

{
  "data": [
    {
      "id": "pool_9w7x4c8a2e6d9b1f7305abcd",
      "label": "US support rotation",
      "sender_dids": ["+14155550100", "+14155550101"],
      "strategy": "sticky",
      "created_at": "2026-09-14T12:00:00.000Z",
      "updated_at": "2026-09-14T12:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_pool_list",
    "timestamp": "2026-09-08T12:00:00Z",
    "pagination": {
      "has_more": false,
      "next_cursor": null
    }
  }
}

3. Send through the pool

POST /api/v1/messages/sms

Request

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": "+14155552671",
    "sender_pool_id": "pool_9w7x4c8a2e6d9b1f7305abcd",
    "body": "Your pickup is ready at counter 4."
  }'

Omit from and pass sender_pool_id; the service resolves the sender via the pool’s strategy. When both are set, the pool wins — same precedence Twilio uses for Messaging Services vs From. The echoed envelope names the resolved sender:

{
  "data": {
    "id": "msg_9e8d7c6b5a4f3021e5d6c7b8a1b2c3d4",
    "channel": "sms",
    "to": "+14155552671",
    "from": "+14155550100",
    "body": "Your pickup is ready at counter 4.",
    "status": "queued",
    "created_at": "2026-09-14T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_pool_send",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

The full send-and-track chain (status polls, DLR webhooks) is on the Messaging samples page.

4. Preview the pick

GET /api/v1/messaging/sender-pools/{id}/preview?recipient=<E.164>

Request

curl "https://api.orbit.devotel.io/api/v1/messaging/sender-pools/pool_9w7x4c8a2e6d9b1f7305abcd/preview?recipient=%2B14155552671" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Preview is strictly read-only: it never persists stickiness state, advances the round-robin counter, or mutates production routing. Use it to verify exactly which DID a pool hands a recipient before you wire the pool into a campaign:

{
  "data": {
    "pool_id": "pool_9w7x4c8a2e6d9b1f7305abcd",
    "recipient": "+14155552671",
    "assigned_sender_did": "+14155550101",
    "strategy": "sticky"
  },
  "meta": {
    "request_id": "req_pool_preview",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

5. Swap the strategy

PATCH /api/v1/messaging/sender-pools/{id}

Request

curl -X PATCH "https://api.orbit.devotel.io/api/v1/messaging/sender-pools/pool_9w7x4c8a2e6d9b1f7305abcd" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "strategy": "round_robin" }'

PATCH must carry at least one of label, sender_dids, or strategy; the response echoes the full pool so the diff (strategy moved sticky → round_robin, updated_at bumped) is visible:

{
  "data": {
    "id": "pool_9w7x4c8a2e6d9b1f7305abcd",
    "label": "US support rotation",
    "sender_dids": ["+14155550100", "+14155550101"],
    "strategy": "round_robin",
    "created_at": "2026-09-14T12:00:00.000Z",
    "updated_at": "2026-09-14T12:05:00.000Z"
  },
  "meta": {
    "request_id": "req_pool_update",
    "timestamp": "2026-09-08T12:05:00Z"
  }
}

The pool cache refreshes within seconds, so the next send uses the new strategy immediately.

These failures cover the pool endpoints shown above. Each block is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface. 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_senderpoa1",
      "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_senderpoa1f",
      "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": "sender_dids", "value": "+1415##50100", "expected": "E.164 numbers, short codes, or alphanumeric sender IDs (1-50 entries, no duplicates)" }
    },
    "meta": {
      "request_id": "req_senderpob2",
      "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 valid sender_dids entries instead of blind-retrying the same body. A pool whose members were all pruned after creation surfaces the same status with code SENDER_POOL_EMPTY on the next send or preview — add at least one DID before sending through it.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_senderpoc3",
      "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": "CONFLICT",
      "message": "The sender is already claimed by another pool in this workspace.",
      "status": 409,
      "details": { "sender_did": "+14155550100" }
    },
    "meta": {
      "request_id": "req_senderpod4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Sender membership is single-owner: a sender one pool already holds is excluded from every other pool’s member selector. Move the sender out of its current pool (or drop it from this request) and resend — repeating the same body re-conflicts deterministically, so this is a fix-then-resend class, not a retry class.

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.
422 `SENDER_POOL_EMPTY`	the pool has no usable senders	Refill, then resend. Add at least one DID to the pool; a retry with the same (empty) pool always re-fails.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
409 `CONFLICT`	a sender is already claimed by another pool	Fix, then resend. Sender membership is single-owner — move the sender out of its current pool first; a blind retry re-conflicts.

API Reference

All Endpoints

Errors worth branching on

Worked request and response samples

1. Create a pool

2. List pools

3. Send through the pool

4. Preview the pick

5. Swap the strategy