> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot port-out rejections: PIN gate and carrier failures

> Decode the three port-out rejections — 401 PORT_OUT_PIN_MISMATCH (PIN protection on, missing or wrong PIN), 502 CARRIER_PORT_OUT_FAILED (carrier rejected; the claim rolls back and the number stays yours), and 422 PORT_OUT_NOT_SUPPORTED (no self-serve adapter; move through support) — and move the number when you actually want it to move.

# 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.

<Note>
  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](/numbers/porting). Purchase-step failures are on
  [Troubleshoot number purchase failures](/troubleshooting/numbers-provisioning-failed).
</Note>

## Port-out lifecycle recap

A port-out runs three stages; the ownership model behind them is
[Port-out lifecycle and ownership model](/concepts/number-port-out-model):

1. **Submitted** — your request passes the status, PIN, and concurrency gates and
   the number flips to `port_out_pending`.
2. **Carrier cycle** — the gaining carrier validates and schedules a Firm Order
   Commitment (FOC) date. The cancel window closes when the carrier locks the
   order.
3. **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`:

```bash theme={null}
# 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:

```bash theme={null}
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:

1. **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.
2. **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.
3. **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:

1. **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.
2. **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.
3. **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.

## See also

* [Port numbers out safely](/guides/port-out-numbers) — the full port-out runbook:
  pre-flight, PIN protection, single and batch submit, tracking, and cancellation.
* [Port-out lifecycle and ownership model](/concepts/number-port-out-model) — the
  state machine, the concurrency guards, and the PIN gate this page works through.
* [Numbers overview](/numbers/overview) and [Porting](/numbers/porting) — the
  endpoint-level reference for both directions.
* [Error codes reference](/reference/error-codes) — the full code catalogue.