Troubleshoot port-out rejections

A port-out that never reaches the carrier — or reaches it and gets refused back — surfaces one of three codes. Work the branch that matches your code; all three are rejected before anything irreversible happens, so the number stays in your account in every case.

This page covers the losing-side (port-OUT) rejections. Port-in failures — a rejected LOA or carrier review on a number you are bringing INTO Orbit — are part of the porting flow. Purchase-step failures are on Troubleshoot number purchase failures.

Port-out lifecycle recap

A port-out runs three stages; the ownership model behind them is Port-out lifecycle and ownership model:

Submitted — your request passes the status, PIN, and concurrency gates and the number flips to port_out_pending.
Carrier cycle — the gaining carrier validates and schedules a Firm Order Commitment (FOC) date. The cancel window closes when the carrier locks the order.
Released / failed — the carrier completes the cutover (number gone) or the order fails / is cancelled (number back at its prior status).

The three rejections below stop before or at the carrier-dispatch step, so none of them strands the number in a phantom pending state.

Decision table

Code	What happened	Recover by
`401 PORT_OUT_PIN_MISMATCH`	PIN protection is enabled on the number and the submitted `port_out_pin` was missing or wrong. The gate runs before carrier dispatch, so the carrier portal never sees the attempt.	Present the correct PIN in the retry body. If the PIN is lost, rotate it (below) — there is no recovery path for a forgotten PIN.
`502 CARRIER_PORT_OUT_FAILED`	The carrier rejected or errored the order — invalid account details, a carrier-side freeze, or an upstream failure. The atomic claim rolls back to the prior status, so the number stays yours.	Confirm the gaining carrier’s OCN and the account data you submitted, fix what the carrier rejected, and retry. The response carries the carrier’s message.
`422 PORT_OUT_NOT_SUPPORTED`	The number’s carrier has no self-serve port-out adapter (the response names the carrier). Nothing is dispatched.	Route the port-out through the carrier’s own portal, or open a support ticket — support dispatches via the carrier portal and records the order id on the number.

Check which rejection you actually received before you retry: a PIN mismatch retried with the same wrong PIN re-rejects, and a 502 retried with unchanged account data re-runs the same carrier rejection.

Recover a PIN-blocked port-out

When protection is enabled, only the PIN holder can dispatch — that is the control working. The PIN is scrypt-hashed at rest and never returned by any read, so a lost PIN cannot be recovered. Rotate a fresh one with POST /api/v1/numbers/:id/port-out-protection:

# Rotate: POST replaces the PIN with a fresh value
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/num_9f4a21/port-out-protection \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "pin": "new-pin-here" }'

Rotation invalidates the old value immediately — distribute the new PIN through your secret store before re-submitting the port-out. If you decide the number should not be protected after all, DELETE the same endpoint to disable protection.

Example: submit with the PIN in the envelope

A correct submission carries the PIN in the request body alongside the carrier account proof and the gaining carrier’s OCN:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/num_9f4a21/port-out \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "losing_carrier_account_number": "ACCT-998877",
    "authorized_person": "Jane Doe",
    "target_carrier_ocn": "6117",
    "port_out_pin": "XF-2841-QS"
  }'

For bulk port-outs (POST /api/v1/numbers/porting/out), one port_out_pin covers the batch — if any protected number is in the batch and the PIN does not match every protected number, the entire request rejects before any wireless dispatch.

Recover a carrier-rejected port-out

A 502 CARRIER_PORT_OUT_FAILED means the request reached the carrier and the carrier said no. Before you retry:

Validate the gaining carrier’s OCN. A wrong target_carrier_ocn routes the order to a carrier that does not hold the gaining account, or the gaining carrier itself rejected an account detail that did not match its records. Confirm the OCN and the account details with the gaining carrier’s portal before re-submitting.
Check the carrier’s message. The error.message usually names the carrier rejection reason — an unpaid balance on the losing carrier account, a mismatched account holder, or a carrier-side freeze. Fix that field, then retry.
Confirm the rollback. After a 502 the number’s status rolled back to its prior portable state, so the next attempt claims it cleanly. If a subsequent submit returns 409 CONFLICT, an earlier attempt is still in flight — list GET /api/v1/numbers/porting/out and cancel the stale order first.

Suspicious-port-out protocol: freeze, vet, release

If a rejection (or the number.port_out.requested webhook) points at a port-out you did not authorize, work the freeze-first order:

Freeze. Set (or rotate) a PIN on the number before anything else. From that point every unauthorized submission fails at the PIN gate with 401 PORT_OUT_PIN_MISMATCH and never reaches the carrier.
Vet. Confirm the request genuinely came from the subscriber — signed authorization matching your account records, and the gaining carrier’s OCN checked against the carrier before you release anything.
Release. Present the correct PIN only once the authorization checks out. The gate holds until then.

These are tenant-owned controls: you decide which numbers carry a PIN and who holds it. Orbit supplies the gate; the posture is yours to set.

When to escalate

Open a support ticket when:

The code is 422 PORT_OUT_NOT_SUPPORTED — support dispatches the port-out through the carrier portal for numbers on a carrier with no self-serve adapter.
A 502 recurs with corrected account details and a validated OCN — the carrier rejection needs operator attention.
A 401 PORT_OUT_PIN_MISMATCH appears and you never set a PIN — an unexpected PIN gate on a number you control means someone with write access enabled protection; treat it as a compromised-credential event and rotate your API keys.

Include the exact meta.request_id of one failed call, the number in E.164 form, and the error code.

Reference

Troubleshoot port-out rejections: PIN gate and carrier failures

Troubleshoot port-out rejections

Port-out lifecycle recap

Decision table

Recover a PIN-blocked port-out

Example: submit with the PIN in the envelope

Recover a carrier-rejected port-out

Suspicious-port-out protocol: freeze, vet, release

When to escalate

See also

​Troubleshoot port-out rejections

​Port-out lifecycle recap

​Decision table

​Recover a PIN-blocked port-out

​Example: submit with the PIN in the envelope

​Recover a carrier-rejected port-out

​Suspicious-port-out protocol: freeze, vet, release

​When to escalate

​See also

Troubleshoot port-out rejections

Port-out lifecycle recap

Decision table

Recover a PIN-blocked port-out

Example: submit with the PIN in the envelope

Recover a carrier-rejected port-out

Suspicious-port-out protocol: freeze, vet, release

When to escalate

See also