Troubleshoot pricing-gate errors

Pricing gates sit on two paths: the billing resolver that prices every send on the send path, and the pricing console/API that maintains the rate card and per-org overrides. A refusal on either path carries one of the PRICING_* codes from the Billing family. This runbook decodes each code to one named fix, and splits the codes by owner: the ones a tenant admin can clear (their own per-org override) from the ones only a platform operator can clear (the rate card, FX snapshots, and wholesale-cost guards — escalate those to the platform and include the billing envelope). This page answers: which gate fired, who owns the fix, and the exact resolution that turns a refused write into a success.

Pricing gates fail closed: a send priced against a missing rate or an override refused by a slot conflict is never dispatched, and a refused override write never persists. Nothing bills in the rejected state — the wallet hold is released with the refusal.

Decode the code

Match error.code from the envelope to a row. The “Owner” column is the split that tells you whether to fix it yourself or escalate.

Code	Where it fires	Owner	The named fix
`PRICING_NOT_CONFIGURED`	Send path — the billing resolver could not find a rate row or a per-org override for the `(channel, sub_type, country, mcc, mnc, prefix)` tuple being charged.	Platform operator	The lane has no published rate. Dry-run the destination against `POST /api/v1/messaging/smpp/carriers/route-quote` to confirm the resolver returns no quote, then the operator publishes a rate for the lane (the tenant escalates with the exact channel/sub-type/country tuple). Never billed until a rate exists.
`PRICING_FX_NOT_CONFIGURED`	Send path and FX warm — the currency-conversion leg is required but the FX provider key is unset.	Platform operator	The FX upstream credential is missing at the platform; the tenant escalates. No tenant-side workaround.
`PRICING_FX_STALE`	Send path — the newest FX snapshot for the required currency pair is older than the 7-day hard ceiling.	Platform operator	FX refresh job is behind or failing; the tenant escalates with the currency pair from `error.details`.
`PRICING_FX_UPSTREAM_FAILED`	FX warm — the FX provider returned a non-2xx while warming a missing rate snapshot.	Platform operator	Transient upstream outage — retry once after a minute; if it persists, escalate (the platform’s provider status page is the source of truth).
`PRICING_FX_UNEXPECTED_BASE`	FX warm — the provider returned a base currency other than USD.	Platform operator	Provider contract breach; escalate — the platform treats USD-base as an invariant.
`PRICING_FX_UNSUPPORTED_CURRENCY`	Send path or override write — the requested currency is outside the supported set.	Caller	Fix the payload: re-issue with a supported currency (check `error.details.requested` if present). Never retried as-is.
`PRICING_RATE_BELOW_WHOLESALE_COST`	Override create (`POST /api/v1/admin/pricing/overrides`) — the absolute price is below the platform’s active wholesale cost for the lane.	Tenant-owned payload	Raise the override price to at least the wholesale cost in `error.details.wholesaleRatePerUnit`, or drop the absolute price and use `overrideMarkupBps` instead.
`PRICING_OVERRIDE_SLOT_CONFLICT`	Override create — a second overlapping active override on the exact same `(organization, channel, sub-type, country, direction)` scope.	Tenant-owned payload	Edit the existing override (`PATCH /api/v1/admin/pricing/overrides/:id` — the id is in `error.details.existingOverrideId`), or end-date the current window before the new one starts. A clean back-to-back handoff (old `effectiveTo` equals new `effectiveFrom`) does not conflict.
`PRICING_RATE_SANITY_VIOLATION`	Rate create/patch — the new cost moved more than 5× above, or below 20% of, the lane’s active cost.	Platform operator	The operator revisits the intended rate — the guard exists to stop a mistyped decimal from repricing a country.
`PRICING_RATE_SLOT_CONFLICT`	Rate create/patch — collides with an already-active rate on the same `(channel, country, direction, sub-type)` slot.	Platform operator	The operator edits or supersedes the colliding active rate instead of inserting a second row into the same slot.
`PRICING_UPLOAD_STALE_CONFLICT`	Rate-file apply — the cached preview went stale before it was applied (another apply changed the rate card in the window).	Platform operator	Re-run the preview and apply the fresh upload; never re-apply the same cached preview — it collides with the slot that changed.

Tenant-owned vs platform-operator-owned

The owner split is the most common escalation mistake. Route the ticket correctly and the fix is one step:

Tenant admin owns the per-org override payloads: an absolute price that dips below wholesale cost (PRICING_RATE_BELOW_WHOLESALE_COST), a second overlapping override on the same scope (PRICING_OVERRIDE_SLOT_CONFLICT), and an unsupported currency on the request (PRICING_FX_UNSUPPORTED_CURRENCY). These are payload fixes — adjust the request and retry.
Platform operator owns everything upstream of the tenant: the rate-card rows (PRICING_NOT_CONFIGURED, PRICING_RATE_SLOT_CONFLICT, PRICING_RATE_SANITY_VIOLATION, PRICING_UPLOAD_STALE_CONFLICT) and the FX chain (PRICING_FX_NOT_CONFIGURED, PRICING_FX_STALE, PRICING_FX_UPSTREAM_FAILED, PRICING_FX_UNEXPECTED_BASE). The tenant has no control surface for these — capture the envelope and escalate.

Worked example — a stuck 422 on the send path

A send to a lane with no published rate refuses with PRICING_NOT_CONFIGURED. Before opening a ticket, dry-run the destination against the route-quote endpoint — it runs the same resolver the send path uses, without billing anything:

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/smpp/carriers/route-quote \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"destination": "+34612345678", "messageCount": 1}'

{
  "data": {
    "decision": "devotel",
    "devotelQuote": null
  },
  "meta": { "request_id": "req_9f2ac1" }
}

devotelQuote: null is the tell: the resolver could not price the destination, so the live send would refuse with PRICING_NOT_CONFIGURED the same way. A configured lane returns a unitPriceCents/totalCents estimate instead. When the dry run is null, escalate with the destination, the channel, and the request_id — the operator publishes the missing rate and the dry run starts returning a quote.

Worked example — an override refused by the wholesale-cost guard

You set an absolute per-message price of 0.002 USD-cents denominated units on a lane whose wholesale cost is 0.0075 per unit. The create refuses because every message billed under that override would charge the org less than the platform pays upstream:

curl -X POST https://api.orbit.devotel.io/api/v1/admin/pricing/overrides \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_8cd21f",
    "channel": "sms",
    "countryCode": "ES",
    "direction": "mt",
    "overrideCostAmount": 0.002,
    "reason": "Promotional rate for Q3 campaign"
  }'

{
  "error": {
    "code": "PRICING_RATE_BELOW_WHOLESALE_COST",
    "message": "Override price 0.002 is below the platform's active wholesale cost 0.0075 (USD) for sms/ES — this would bill the org LESS than Orbit pays upstream on every unit.",
    "status": 422,
    "details": {
      "organizationId": "org_8cd21f",
      "channel": "sms",
      "countryCode": "ES",
      "overrideCostAmount": 0.002,
      "wholesaleRatePerUnit": 0.0075
    }
  },
  "meta": { "request_id": "req_51bb02" }
}

Resolution: pick one of the three fixes — raise overrideCostAmount to at least wholesaleRatePerUnit, swap the absolute price for a markup (overrideMarkupBps, which prices above cost by construction), or narrow the scope (subType, direction) to the lane you actually negotiated. Then retry the same create — it returns 201 with the persisted override. Wholesale cost is a platform-published input; if your agreement prices a lane below it, that is negotiated out-of-band and applied by the operator, not through this endpoint.

Worked example — a second override refused by the slot conflict

A scope already has an active override, and a second create on the exact same scope with an overlapping window refuses with a 409:

{
  "error": {
    "code": "PRICING_OVERRIDE_SLOT_CONFLICT",
    "message": "An override already exists for org \"org_8cd21f\" on this channel/scope (channel \"sms\", country \"ES\", direction \"mt\") whose effective window overlaps this one — id=pricingOverride_7ab3d1. Edit that override (PATCH /admin/pricing/overrides/pricingOverride_7ab3d1) instead of creating a second one, or adjust the effective dates so the two don't overlap; otherwise the resolver would silently pick between them by latest effective date.",
    "status": 409,
    "details": {
      "organizationId": "org_8cd21f",
      "channel": "sms",
      "countryCode": "ES",
      "direction": "mt",
      "existingOverrideId": "pricingOverride_7ab3d1"
    }
  },
  "meta": { "request_id": "req_77e10c" }
}

Resolution — three ways out, one retry:

Edit in place — PATCH /api/v1/admin/pricing/overrides/pricingOverride_7ab3d1 with the new price or markup. Use the id from error.details.existingOverrideId.
Re-scope — add or change a scope field (subType or direction) so the new override covers a different lane.
Schedule a handoff — end-date the current override and start the new one after: set effectiveTo on the existing row (PATCH), then create the new override with effectiveFrom equal to that instant. Half-open windows are exclusive at the boundary, so a back-to-back handoff is not a conflict.

Any of the three turns the next POST into a 201 with the override row in the response body. Deleting the conflicting override and re-creating it also clears the slot, but the PATCH keeps the audit trail intact and is the preferred fix.

Decision checklist

Read error.code and error.status off the envelope; match the row in the decode table above.
Check the Owner column — a tenant-owned row is a payload fix; an operator row is an escalation.
For a send-path refusal, dry-run POST /api/v1/messaging/smpp/carriers/route-quote for the destination and capture the devotelQuote null-vs-priced result.
For an override refusal, take error.details.existingOverrideId / wholesaleRatePerUnit as the ground truth for the fix, adjust the payload, and retry once.
If the row names the operator, escalate with the envelope (see below).

Full-error sample (paste-ready)

A send refused by the resolver on an unpriced lane:

{
  "error": {
    "code": "PRICING_NOT_CONFIGURED",
    "message": "No pricing rate or org override resolves for sms/mt/ES — the lane has no published rate.",
    "status": 422,
    "details": {
      "channel": "sms",
      "direction": "mt",
      "countryCode": "ES"
    }
  },
  "meta": {
    "request_id": "req_4ad90e",
    "timestamp": "2026-09-20T10:15:42Z"
  }
}

What NOT to do

Do not blind-retry a PRICING_* refusal. Every gate in this family is deterministic — the same payload refuses identically until the named fix lands, and a retry loop burns your rate-limit budget.
Do not re-apply a stale rate-file preview after PRICING_UPLOAD_STALE_CONFLICT. Re-run the preview against the current rate card; the stale batch collides with the rows that changed.
Do not delete-and-recreate overrides in a loop to dodge the slot conflict — the guard compares effective windows, and an overlapping recreation refuses the same way. PATCH the existing row or schedule the handoff.
Do not treat a PRICING_FX_* send-path refusal as tenant-fixable. The FX chain is platform-owned; re-sending the same payload while the operator fixes it only re-fails. Escalate once, then retry after the all-clear.
Do not scope an override by MCC/MNC/prefix — the resolver scopes overrides by channel, sub-type, country, and direction only, and the request refuses with a 422 validation error rather than silently broadening the override.

When to escalate

Escalate when the decode row’s Owner column says platform operator, or when a tenant-owned fix still refuses after the payload change named by error.details. Include:

Your tenant ID (GET /api/v1/me → organizationId).
The exact code and the request ID (meta.request_id) from one refused envelope.
For a send-path refusal: the destination, channel, and the route-quote dry-run output (especially devotelQuote: null).
For an override refusal: the override payload you sent and the existingOverrideId / wholesaleRatePerUnit from error.details.
For FX codes: the currency pair and the observed time window.

Reference

Troubleshoot pricing-gate errors (PRICING_NOT_CONFIGURED, PRICING_FX_, PRICING_RATE_, PRICING_OVERRIDE_SLOT_CONFLICT, PRICING_UPLOAD_STALE_CONFLICT)

Troubleshoot pricing-gate errors

Decode the code

Tenant-owned vs platform-operator-owned

Worked example — a stuck 422 on the send path

Worked example — an override refused by the wholesale-cost guard

Worked example — a second override refused by the slot conflict

Decision checklist

Full-error sample (paste-ready)

What NOT to do

When to escalate

See also

​Troubleshoot pricing-gate errors

​Decode the code

​Tenant-owned vs platform-operator-owned

​Worked example — a stuck 422 on the send path

​Worked example — an override refused by the wholesale-cost guard

​Worked example — a second override refused by the slot conflict

​Decision checklist

​Full-error sample (paste-ready)

​What NOT to do

​When to escalate

​See also

Troubleshoot pricing-gate errors

Decode the code

Tenant-owned vs platform-operator-owned

Worked example — a stuck 422 on the send path

Worked example — an override refused by the wholesale-cost guard

Worked example — a second override refused by the slot conflict

Decision checklist

Full-error sample (paste-ready)

What NOT to do

When to escalate

See also