Errors worth branching on

These five failures cover the ads stats sync (POST /api/v1/ads/sync), on every stats pull from the account linker. 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_adsa1",
      "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_adsa1f",
      "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": "campaign_id", "value": "camp_0192", "expected": "an existing campaign id from GET /api/v1/ads/campaigns" }
    },
    "meta": {
      "request_id": "req_adsb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and list campaigns first and resend with an existing campaign id 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_adsc3",
      "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.

402 — Feature gate

  {
    "error": {
      "code": "ADS_ACCOUNT_NOT_LINKED",
      "message": "No ad account is linked to this organization.",
      "status": 402
    },
    "meta": {
      "request_id": "req_adsd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Surface the connect-account screen — the stats/read endpoints still return data; only mutation is gated.

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.
`ADS_ACCOUNT_NOT_LINKED` (402 feature gate)	Surface the connect-account screen	Branch on `error.code`. The stats/read endpoints still return data; only mutation is gated.

Worked samples — ads audiences, campaigns, attribution

Copy a request as written, substitute your own ids, and compare the response envelope — a success in the same { data, meta } shape the numbered error sections spell out. Every operation below supports cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP; for brevity each sample shows cURL and TypeScript — the two most-used — and a link to the per-operation block further down the page carries the other four languages. The sequence at the end (create an audience → bind it to a campaign → read back insights → export attribution) is the path most workspaces take from segment to measured spend.

1. Create a custom audience

POST /api/v1/ads/audiences

Creates a Meta Custom Audience on the connected ad account, optionally linked to a CDP segment so its membership can be synced later. Pass name, an optional description, and an optional segment_id to bind the audience to a segment on creation; leave segment_id out and bind it later at sync time. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/ads/audiences" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_aud_cart_30d" \
  -d '{
  "name": "Cart abandoners — 30d",
  "description": "Contacts who abandoned a checkout in the last 30 days",
  "segment_id": "seg_8c1f4e2a9b3d5f7e"
}'

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/ads/audiences', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'idem_aud_cart_30d',
  },
  body: JSON.stringify({
    name: 'Cart abandoners — 30d',
    description: 'Contacts who abandoned a checkout in the last 30 days',
    segment_id: 'seg_8c1f4e2a9b3d5f7e',
  }),
})
console.log(await res.json())

Response

{
  "data": {
    "audience_id": "2384745930102",
    "name": "Cart abandoners — 30d",
    "segment_id": "seg_8c1f4e2a9b3d5f7e",
    "created_at": "2026-09-08T12:00:00.000Z",
    "last_synced_at": null,
    "last_sync_count": null
  },
  "meta": {
    "request_id": "req_ads_create",
    "timestamp": "2026-09-08T12:00:00.000Z"
  }
}

The persisted record carries the Meta-assigned audience_id plus the segment_id link you sent. last_synced_at and last_sync_count stay null until the first /sync run pushes membership; read the audience back any time with GET /api/v1/ads/audiences to see those two fields fill in. The audience is available for targeting on Meta as soon as it is created — there is no separate status poll on Orbit’s side.

2. List ad campaigns

GET /api/v1/ads/campaigns

Returns the click-to-chat campaigns on the connected Meta ad account as a cursor-paginated list. When no ad account is connected the list is empty rather than an error, so the dashboard renders cleanly before setup. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ads/campaigns" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/ads/campaigns', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Response

{
  "data": [
    {
      "id": "1202103894011",
      "name": "Q3 click-to-WhatsApp — cart recovery",
      "status": "PAUSED",
      "objective": "OUTCOME_LEADS",
      "daily_budget": "2500",
      "created_time": "2026-08-14T09:31:00+0000"
    },
    {
      "id": "1202103894124",
      "name": "Messenger retargeting — lapsed buyers",
      "status": "ACTIVE",
      "objective": "OUTCOME_ENGAGEMENT",
      "daily_budget": "4000",
      "created_time": "2026-08-02T14:05:00+0000"
    }
  ],
  "meta": {
    "request_id": "req_ads_list",
    "timestamp": "2026-09-08T12:00:00.000Z",
    "pagination": {
      "cursor": "1202103894124",
      "has_more": true,
      "total": 27
    }
  }
}

Page forward with ?cursor=1202103894124 until has_more is false. Budget strings come straight from Meta in the account’s currency — surface GET /api/v1/ads/status to read what that currency is.

3. Read one campaign with its insights

GET /api/v1/ads/campaigns/{id}

Returns one campaign plus a flattened insights summary (impressions, reach, clicks, CTR, spend, CPC, and conversations started) for the details view. The insights block is always included — no query param is needed. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ads/campaigns/1202103894011" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const id = '1202103894011'
const res = await fetch(`https://api.orbit.devotel.io/api/v1/ads/campaigns/${id}`, {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Response

{
  "data": {
    "campaign_id": "1202103894011",
    "insights": {
      "impressions": "48120",
      "reach": "31402",
      "clicks": "1187",
      "ctr": "2.466750",
      "spend": "812.43",
      "cpc": "0.684355",
      "conversations_started": "214"
    }
  },
  "meta": {
    "request_id": "req_ads_get",
    "timestamp": "2026-09-08T12:00:00.000Z"
  }
}

All metric fields are flattened onto one object (not the one-element array Meta’s Graph returns), so the details read is a single top-level insights.

4. Read attribution rollups per channel

GET /api/v1/ads/ctwa/attribution

Rolls up Click-to-WhatsApp (and RCS) entry points captured on inbound messages by ad: entry volume, distinct first-touched contacts, first-touch attributed revenue from local WhatsApp catalog orders, and — when a Meta ad account is connected — ad-spend-overlaid ROAS/ROI per ad. window_days (default 30, max 365) sets the look-back for both sides of the ratio. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ads/ctwa/attribution?window_days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/ads/ctwa/attribution?window_days=30', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Response

{
  "data": {
    "reporting_currency": "USD",
    "window_days": 30,
    "total_entry_count": 614,
    "total_unique_contacts": 402,
    "total_attributed_revenue_cents": 915230,
    "total_unconvertible_revenue_cents": 0,
    "total_spend_cents": 81243,
    "roas": 11.27,
    "roi_pct": 1027.0,
    "cost_status": "with_spend",
    "spend_available": true,
    "ads": [
      {
        "ad_id": "9412048830112",
        "source_type": "ad",
        "source_url": "https://www.facebook.com/ads/9412048830112",
        "headline": "Free shipping this week",
        "body": "Tap to chat and claim your code",
        "media_type": "image",
        "entry_count": 214,
        "unique_contacts": 187,
        "first_seen": "2026-08-14T09:31:12.000Z",
        "last_seen": "2026-09-08T11:58:02.000Z",
        "attributed_revenue_cents": 610400,
        "unconvertible_revenue_cents": 0,
        "revenue_by_currency": [
          { "currency": "USD", "amount_cents": 610400, "converted": true }
        ],
        "spend_cents": 60211,
        "roas": 10.14,
        "roi_pct": 914.0,
        "cost_status": "with_spend"
      },
      {
        "ad_id": "9412048830499",
        "source_type": "ad",
        "source_url": "https://www.facebook.com/ads/9412048830499",
        "headline": "Still thinking it over?",
        "body": "Ask us anything on WhatsApp",
        "media_type": "video",
        "entry_count": 400,
        "unique_contacts": 215,
        "first_seen": "2026-08-10T15:02:44.000Z",
        "last_seen": "2026-09-08T10:11:57.000Z",
        "attributed_revenue_cents": 304830,
        "unconvertible_revenue_cents": 0,
        "revenue_by_currency": [
          { "currency": "USD", "amount_cents": 304830, "converted": true }
        ],
        "spend_cents": 21032,
        "roas": 14.49,
        "roi_pct": 1349.0,
        "cost_status": "with_spend"
      }
    ]
  },
  "meta": {
    "request_id": "req_ads_attr",
    "timestamp": "2026-09-08T12:00:00.000Z"
  }
}

When no ad account is connected the same shape comes back with spend_available: false, roas: null, and cost_status: "no_spend" — entry counts and attributed revenue still roll up, only the spend overlay degrades.

5. Read audience status transitions

GET /api/v1/ads/audiences and GET /api/v1/ads/status

There are two status surfaces. GET /api/v1/ads/audiences is the per-audience view — the sync metadata on each stored audience tells you whether it has ever pushed membership and when. GET /api/v1/ads/status is the connection-level view the dashboard polls — whether a Meta ad account is linked, which ad_account_id, the currency, and whether a Conversions API dataset is set. Request — per-audience sync state

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ads/audiences" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/ads/audiences', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Response

{
  "data": {
    "audiences": [
      {
        "audience_id": "2384745930102",
        "name": "Cart abandoners — 30d",
        "segment_id": "seg_8c1f4e2a9b3d5f7e",
        "created_at": "2026-09-08T12:00:00.000Z",
        "last_synced_at": "2026-09-08T13:40:11.000Z",
        "last_sync_count": 48210
      },
      {
        "audience_id": "2384745930899",
        "name": "High-LTV lookalike seed",
        "segment_id": null,
        "created_at": "2026-08-01T08:12:00.000Z",
        "last_synced_at": null,
        "last_sync_count": null
      }
    ]
  },
  "meta": {
    "request_id": "req_ads_aud_list",
    "timestamp": "2026-09-08T14:00:00.000Z"
  }
}

last_synced_at: null marks an audience that has not yet synced — the empty state before the first POST .../sync. A filled pair means the last push completed and carried last_sync_count members. Request — connection status

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/ads/status" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/ads/status', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Response

{
  "data": {
    "connected": true,
    "ad_account_id": "act_2384745930",
    "connected_at": "2026-07-30T10:00:00.000Z",
    "currency": "USD",
    "dataset_id": "7728814502",
    "auto_ctwa_conversion": true
  },
  "meta": {
    "request_id": "req_ads_status",
    "timestamp": "2026-09-08T14:00:00.000Z"
  }
}

Before any account is linked the same endpoint answers 200 with connected: false, ad_account_id: null, and currency: null — a clean pre-setup state, not an error.

6. A 4-op sequence: audience → campaign → insights → attribution

The path from a CDP segment to a measured ROAS. Run the four operations in order; the id from step 1 feeds step 2, the campaign id from step 2 feeds step 3, and step 4 closes the loop.

Sequence

# 1. Create the audience, bound to a segment.
curl -X POST "https://api.orbit.devotel.io/api/v1/ads/audiences" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cart abandoners — 30d","segment_id":"seg_8c1f4e2a9b3d5f7e"}'

# 2. Sync the segment's membership into it (bind + push).
curl -X POST "https://api.orbit.devotel.io/api/v1/ads/audiences/2384745930102/sync" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"segment_id":"seg_8c1f4e2a9b3d5f7e","mode":"add"}'

# 3. Create a click-to-chat campaign that routes taps to WhatsApp.
curl -X POST "https://api.orbit.devotel.io/api/v1/ads/campaigns" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q3 cart recovery","destination":"WHATSAPP","daily_budget":2500,"ad_text":"Still thinking it over? Chat with us."}'

# 4. Read back the campaign's insights, then export the attribution rollup.
curl -X GET "https://api.orbit.devotel.io/api/v1/ads/campaigns/1202103894011" \
  -H "X-API-Key: dv_live_sk_your_key_here"
curl -X GET "https://api.orbit.devotel.io/api/v1/ads/ctwa/attribution?window_days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

The attribution export in step 4 attributes local WhatsApp catalog revenue first-touch to the entry ad and overlays Meta ad spend for ROAS — the report the dashboard’s ads console renders.

API Reference

All Endpoints

Errors worth branching on