Reason codes

After this page you can read any refusal the router made, say whose problem it is, and turn a code into a filter, a report row or an alert. Whenever the router declines to do something it records a reason code and a sentence. The code is short, stable and never renamed, so you can filter, group and page on it; the sentence is what a person reads.

There are two families. An unrouted reason ends the call: a gate failed before any target was dialled, or every target was tried and none took it. A call has at most one, and it is stored on the call itself. A skip reason passes over one entry in the routing plan while the call carries on down it; one call can collect many, and they live in the call's waterfall.

Unrouted reasons

These are listed in the order the router tests them, which is also the order of decreasing blast radius: your account, then the campaign, then the caller, then the plan. The first one that applies is the one the call gets, so a call on a campaign that is both closed and capped reads campaign_closed.

What to do about each one

Skip reasons

Why one target on the routing plan was passed over. The call carried on to the next entry, so a call full of skips can still connect — and usually does. A skip is only a problem when every entry has one, which is no_eligible_target.

What to do about each one

• paused, buyer_paused and no_destination are configuration. Somebody switched the target or its buyer off, or saved a target with nothing to dial. Nothing recovers on its own.
• suppressed is the platform protecting you: a destination that failed repeatedly is stood down briefly and tried again without anybody doing anything. Repeated suppression is a conversation to have with the buyer.
• closed, state, capped, buyer_capped, spend_capped and concurrency are the terms you agreed with the buyer, working. If they skip more traffic than you expected, the terms are wrong, not the router.
• duplicate is the target's duplicate window, not the campaign's repeat-caller policy. The two are different settings with different owners — see Repeat and blocked callers.
• tag_filter names the tag that failed in the stored sentence, so you can see which rule fired without reading the whole filter set. See Filters and tags.
• no_bid, timeout and error are the buyer's endpoint. The ping ledger has the request that was sent and the answer that came back, which is what their engineer will ask for.

The sentence is written at the time

Each table above shows the context-free sentence: the one that is true on its own, with no call in front of it. What the router actually stores is richer, because it knows the names and the figures at the moment it refuses. Those stored sentences never change afterwards — a cap you raise tomorrow does not rewrite what yesterday's call says about itself.

A code the platform does not recognise still produces a sentence rather than an error, because this runs inside a live call: an unknown code reads "The call was not routed (<code>)." Treat an unknown code the same way — as "not routed" — and show the sentence, which always arrives beside it.

Whose problem it is

Every code carries an owner, which is the console's way of sending a reader to the right screen. It is one of five words, and it is stable — an integration can route an alert on it without parsing English.

What a publisher is told

A publisher sees the calls they sent you, and they see why a call was not connected — but not in your words. Your sentences name your wallet, your plan and your buyers' caps, and none of that is a partner's business. So a publisher's call page is built from a different table, never filtered from yours: nothing the router stored is copied into a publisher's answer.

What a publisher needs to know is whether the fault was theirs — the caller, the hour, the cap they were given — or not. That is exactly what these sentences say, and no more.

• The first three codes collapse into one sentence on purpose. "The wallet is empty" is a thing a seller would much rather tell a partner itself, and a lapsed subscription is nobody else's business.
• The codes that are genuinely about the traffic — a blocked caller, a withheld number, the hour, a repeat caller — are passed through in full, because a publisher can act on them.
• Skip reasons are never shown to a publisher at all. They are about your buyers, and a publisher does not see your buyers.
• Your own call page still shows the full sentence. The two are different views of one call, not two records; see The call waterfall.

Reading a code out of the API

A call carries reasonCode and reasonSentence, and both are null on a call that routed. reasonSentence is the sentence the router stored at the time, falling back to the context-free one if none was stored.

{
  "id": "0b9f6c1e-52a4-4a0e-9f0a-3d1c7e8b2a11",
  "ref": "CA-482137",
  "outcome": "unrouted",
  "status": "no_answer",
  "reasonCode": "campaign_capped",
  "reasonSentence": "The campaign Acme Health — Inbound has reached its daily cap of 500 calls."
}

The call.unrouted event carries the code as reason, the stored sentence beside it, and action — what the caller then heard.

{
  "id": "req_5f0c2a91b7d34e10",
  "event": "call.unrouted",
  "createdAt": "2026-09-20T14:03:12.418Z",
  "data": {
    "callId": "0b9f6c1e-52a4-4a0e-9f0a-3d1c7e8b2a11",
    "ref": "CA-482137",
    "status": "rejected",
    "campaignId": "6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d",
    "campaignName": "Acme Health — Inbound",
    "reason": "workspace_unfunded",
    "sentence": "The workspace wallet is empty, so the call was not routed. Add funds under Wallet & billing and routing resumes on the next call.",
    "action": "hangup"
  }
}

Worked example: which refusal is costing the most

Yesterday was quiet on Acme Health — Inbound and nobody knows why. Ask for the calls behind one suspicion, then ask the whole day to rank itself. This needs a key with calls:read and reports:read; see API keys.

# Every call yesterday that a full campaign cap turned away
curl -G "https://api.buy3.io/api/v1/calls" \
  -H "Authorization: Bearer $BUY3_API_KEY" \
  --data-urlencode "reason=campaign_capped" \
  --data-urlencode "from=2026-09-19T05:00:00Z" \
  --data-urlencode "to=2026-09-20T05:00:00Z"

# And the same window grouped by reason, worst first
curl -G "https://api.buy3.io/api/v1/reports/summary" \
  -H "Authorization: Bearer $BUY3_API_KEY" \
  --data-urlencode "groupBy=reason" \
  --data-urlencode "from=2026-09-19T05:00:00Z" \
  --data-urlencode "to=2026-09-20T05:00:00Z"

{
  "groupBy": ["reason"],
  "rows": [
    {
      "dimensions": [{
        "dimension": "reason",
        "key": "campaign_closed",
        "label": "Outside campaign hours",
        "sentence": "The call arrived outside the campaign's hours of operation.",
        "owner": "campaign"
      }],
      "calls": 61,
      "connected": 0,
      "converted": 0,
      "unrouted": 61,
      "connectRate": 0,
      "conversionRate": null,
      "revenueCents": 0
    }
  ]
}

Sixty-one calls arrived outside the campaign's hours, and the row hands you the label, the sentence and the owner without a second lookup. owner is campaign, so the fix is the campaign's hours — most often a schedule saved in the wrong time zone. Note that a report grouped by reason counts only unrouted calls: routed calls have no reason and are left out of the rows, though they are still in totals.

Using the codes

• Filter the call log by reason to see every call a closed campaign or a full cap cost you, then export it — see Exports.
• Group a report by reason to find the one worth fixing first. Rank by calls, not by how loud the complaint was.
• Alert on them: subscribe a webhook to call.unrouted and page somebody when workspace_unfunded or no_eligible_target turns up. The first is money; the second is a plan that has quietly stopped having anyone in it.
• Branch on the code, print the sentence. The code is the contract and the sentence is the copy. Writing your own English for a code means maintaining a second copy of this page.
• Expect new codes. They are only ever added, never renamed or removed. An integration that treats an unknown code as "not routed" and shows its sentence never needs changing.

Next steps