Errors worth branching on

These five failures cover the import job create + status poll (POST /api/v1/imports, GET /api/v1/imports/), hammered by every onboarding wizard. 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_importsa1",
      "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_importsa1f",
      "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": "source_id", "value": "imp_hs_0192", "expected": "the source_id returned by POST /api/v1/imports" }
    },
    "meta": {
      "request_id": "req_importsb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and poll GET /api/v1/imports/ for the job state instead of re-posting the same payload 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_importsc3",
      "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": "IMPORT_SOURCE_NOT_CONNECTED",
      "message": "The import source handshake has not completed for this job.",
      "status": 402
    },
    "meta": {
      "request_id": "req_importsd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Keep polling the job status; re-run the connect wizard only when the job reports source_lost.

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.
`IMPORT_SOURCE_NOT_CONNECTED` (402 feature gate)	page-specific gating	Branch on `error.code`. Keep polling the job status; re-run the connect wizard only when the job reports source_lost.

Worked request and response samples

Copy the request as written, substitute your own ids, and compare the response envelope — a success in the same shape the numbered error sections spell out.

Start a contact import

POST /api/v1/imports

Uploads run as jobs — the returned job id is your handle for progress polling and the final row report. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/imports" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "contacts",
  "file_id": "file_91c4e2a8b6d3f5e7",
  "mapping": {
    "phone": "msisdn",
    "first_name": "firstName"
  }
}'

{
  "data": {
    "id": "job_5e2b9c47d1a0f683",
    "kind": "contacts",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_imports",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Worked provider-import samples

A migration off Twilio, Telnyx, Klaviyo, or MessageBird is a five-step chain: hand over credentials, preview what the source holds, start the run, watch the job, and cancel or roll back if the preview lied. Every response below keeps the { data, meta } envelope. The samples past the Twilio manual-credentials step are numbered cURL + Node.js pairs; the Node tab uses the orbit.request escape hatch because the SDK has no typed imports namespace yet — vendor it from packages/sdk-node, per the SDK index. For the wizard-side walkthrough of the same chain, see the import wizard guide. Credentials are used to READ the source account only — no outbound voice or SMS is ever routed through the source provider as a result of the import; outbound traffic keeps exiting via Devotel’s wholesale softswitch.

1. Hand over the credentials — get back an opaque envelope

The run and dry-run calls never take raw provider keys. You exchange the provider credential ONCE for an encrypted envelope and pass that envelope forward. Use whichever intake the provider supports:

Twilio (manual fallback) — Account SID + Auth Token, when the OAuth flow below is unavailable.
Telnyx — a V2 API key (starts with KEY).
Klaviyo — a private API key (starts with pk_).
MessageBird — an access key (live_ / test_ prefixed or bare).

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/manual-credentials" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSid": "ACf4b8c2d1e90517a3f6b0d8e2c4a6f18b",
    "authToken": "your_twilio_auth_token"
  }'

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/telnyx/manual-credentials" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "KEY0123456789abcdef0123456789abcdef",
    "accountId": "Production account"
  }'

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/klaviyo/manual-credentials" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "pk_0123456789abcdef0123456789" }'

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/messagebird/manual-credentials" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "live_0123456789abcdef0123456789" }'

Each intake returns the same shape — the raw key is never echoed back, only the envelope:

200

{
  "data": {
    "envelope": "enc:v1:g8K2xQ…opaque…",
    "accountId": "Production account"
  },
  "meta": {
    "request_id": "req_importscred01",
    "timestamp": "2026-09-14T12:00:00Z"
  }
}

Carry data.envelope into every dry-run and run call from here on. A malformed key fails the format check locally with a 422 before any upstream round-trip (see the 422 — Credentials branch below); Twilio additionally returns accountSid alongside the envelope.

2. Preview the import — dry-run before anything is written

POST /api/v1/imports/{source}/dry-run

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope": "enc:v1:g8K2xQ…opaque…",
    "entities": ["phone_numbers", "templates", "contacts"],
    "conversationDays": 90
  }'

const res = await orbit.request('POST', '/api/v1/imports/twilio/dry-run', {
  body: {
    envelope,
    entities: ['phone_numbers', 'templates', 'contacts'],
    conversationDays: 90,
  },
})
console.log(res.data)

{
  "data": {
    "source": "twilio",
    "entities": [
      { "kind": "phone_numbers", "estimatedCount": 42, "knownConflicts": 2 },
      { "kind": "templates", "estimatedCount": 17, "knownConflicts": 0 },
      { "kind": "contacts", "estimatedCount": 12840, "knownConflicts": 316 }
    ],
    "etaSeconds": 690,
    "generatedAt": "2026-09-14T12:00:01Z"
  },
  "meta": {
    "request_id": "req_importsdry02",
    "timestamp": "2026-09-14T12:00:01Z"
  }
}

Read three things before committing: estimatedCount per entity, knownConflicts (rows already on the Orbit side — a phone number already in the pool, a contact already imported), and the etaSeconds total. The valid entity kinds are phone_numbers, messaging_services, templates, contacts, conversations, channels, flows, inboxes, tags, teammates, lists, segments — each source supports a subset, and unsupported kinds are rejected by schema. Twilio conversation history caps at 90 days; past that the provider returns nothing more. Nothing is written at this step.

3. Start the run — get a job id back

POST /api/v1/imports/{source}/run

Send the same envelope and entity selection you previewed, plus an optional per-entity conflict policy (skip, overwrite, or merge).

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/run" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Idempotency-Key: mig-twilio-2026-09-14-01" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope": "enc:v1:g8K2xQ…opaque…",
    "entities": ["phone_numbers", "templates", "contacts"],
    "conversationDays": 90,
    "conflictPolicy": { "phone_numbers": "skip", "contacts": "merge" }
  }'

const res = await orbit.request('POST', '/api/v1/imports/twilio/run', {
  headers: { 'Idempotency-Key': 'mig-twilio-2026-09-14-01' },
  body: {
    envelope,
    entities: ['phone_numbers', 'templates', 'contacts'],
    conversationDays: 90,
    conflictPolicy: { phone_numbers: 'skip', contacts: 'merge' },
  },
})
const { jobId } = res.data

{
  "data": {
    "jobId": "job_7a1c4e92b0d3f586",
    "status": "pending"
  },
  "meta": {
    "request_id": "req_importsrun03",
    "timestamp": "2026-09-14T12:00:02Z"
  }
}

The jobId is the handle for every later step. Credentials ride the job as an encrypted envelope, are decrypted only inside the worker, and are redacted from the job record once the job reaches a terminal status.

4. Poll the job — point-in-time snapshot of progress

GET /api/v1/imports/{jobId}

curl -X GET "https://api.orbit.devotel.io/api/v1/imports/job_7a1c4e92b0d3f586" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.request(
  'GET',
  '/api/v1/imports/job_7a1c4e92b0d3f586',
)
for (const entity of res.data.progress) {
  console.log(entity.kind, entity.imported, '/', entity.total)
}

{
  "data": {
    "id": "job_7a1c4e92b0d3f586",
    "source": "twilio",
    "status": "running",
    "progress": [
      {
        "kind": "phone_numbers",
        "total": 42,
        "imported": 40,
        "skipped": 2,
        "failed": 0,
        "cursor": null,
        "conflicts": [
          {
            "upstreamId": "PN2f9c0a8e4b6d1c3a5e7f9a0b2c4d6e8f",
            "orbitId": "num_3b8f1c2a9d",
            "reason": "number already in pool",
            "appliedPolicy": "skip"
          }
        ]
      },
      {
        "kind": "contacts",
        "total": 12840,
        "imported": 5210,
        "skipped": 301,
        "failed": 0,
        "cursor": "CI9f8e7d6c5b4a",
        "conflicts": []
      }
    ],
    "startedAt": "2026-09-14T12:00:04Z",
    "completedAt": null,
    "failureReason": null,
    "rollbackAt": null,
    "rollbackCount": 0,
    "createdAt": "2026-09-14T12:00:02Z"
  },
  "meta": {
    "request_id": "req_importsget04",
    "timestamp": "2026-09-14T12:01:10Z"
  }
}

status walks pending → running → succeeded | failed | cancelled. Poll on a 2–5 second cadence, or subscribe to GET /api/v1/imports/{jobId}/progress for the same counters as a live Server-Sent Events stream (snapshot first frame, then progress/status events, then a terminal end event). A terminal job reports its per-row failures in progress[].failed and its collisions in progress[].conflicts — resolve those in the wizard’s reconcile step.

5. Prefer the OAuth path for Twilio (no secrets to paste)

The manual-credentials paste is the fallback. When Twilio Connect is available the flow is two browser steps and zero secrets through the clipboard.

curl -X GET "https://api.orbit.devotel.io/api/v1/imports/twilio/connect" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.request('GET', '/api/v1/imports/twilio/connect')
open(res.data.authorizeUrl) // hand the operator the Twilio consent page

{
  "data": {
    "authorizeUrl": "https://www.twilio.com/authorize?response_type=code&client_id=…&redirect_uri=…&scope=get-all&state=twoa_4f8c2e1d9b7a5c3e0f2d4a6b8c1e3d5f&code_challenge=…&code_challenge_method=S256",
    "state": "twoa_4f8c2e1d9b7a5c3e0f2d4a6b8c1e3d5f"
  },
  "meta": {
    "request_id": "req_importsconn05",
    "timestamp": "2026-09-14T12:00:00Z"
  }
}

Open authorizeUrl, and the operator approves on Twilio’s page. Twilio then redirects the browser to the callback — you do not construct this URL yourself, Twilio does, with the authorization code and the single-use state from step A:

Step B — Twilio redirects the browser here (no client code needed)

GET /api/v1/imports/twilio/callback?code=qR8x2P…&state=twoa_4f8c2e1d9b7a5c3e0f2d4a6b8c1e3d5f

302

HTTP/1.1 302 Found
Location: /onboarding/import/twilio?envelope=enc:v1:g8K2xQ…&accountSid=ACf4b8c2d1e90517a3f6b0d8e2c4a6f18b

The raw access token never reaches the browser — the callback exchanges the code server-side, encrypts the credentials, and 302s back into the wizard with the same opaque envelope the manual path returns. A user who declines the consent lands on a 400 TWILIO_OAUTH_DENIED; a state older than 10 minutes or posted twice lands on 400 INVALID_OAUTH_STATE. When Twilio Connect is not configured at all, step A returns 503 TWILIO_CONNECT_NOT_CONFIGURED — fall back to the manual-credentials intake in step 1.

6. Cancel an in-flight job

POST /api/v1/imports/{jobId}/cancel

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/job_7a1c4e92b0d3f586/cancel" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Idempotency-Key: mig-twilio-cancel-2026-09-14-01"

const res = await orbit.request(
  'POST',
  '/api/v1/imports/job_7a1c4e92b0d3f586/cancel',
  { headers: { 'Idempotency-Key': 'mig-twilio-cancel-2026-09-14-01' } },
)
console.log(res.data)

{
  "data": {
    "cancelled": true,
    "status": "cancelled"
  },
  "meta": {
    "request_id": "req_importscxl06",
    "timestamp": "2026-09-14T12:02:31Z"
  }
}

The worker re-checks status between pages, so a cancel takes effect at the next page boundary rather than mid-row. Only pending or running jobs can be cancelled — cancelling a finished job returns the 409 IMPORT_NOT_CANCELLABLE shape below. Rows already imported stay imported; to undo a completed import, roll back instead.

7. Roll back a completed import — undo what it wrote

POST /api/v1/imports/{jobId}/rollback

Destructive: deletes every contact the batch created, in one transaction, and records the rollback on the job. Owner or admin role required; the job must be in a terminal status.

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/job_7a1c4e92b0d3f586/rollback" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Idempotency-Key: mig-twilio-rollback-2026-09-14-01"

const res = await orbit.request(
  'POST',
  '/api/v1/imports/job_7a1c4e92b0d3f586/rollback',
  { headers: { 'Idempotency-Key': 'mig-twilio-rollback-2026-09-14-01' } },
)
console.log(res.data.deletedCount)

{
  "data": {
    "rolledBack": true,
    "deletedCount": 12524
  },
  "meta": {
    "request_id": "req_importsrb07",
    "timestamp": "2026-09-14T12:30:00Z"
  }
}

A job already rolled back returns 409 ALREADY_ROLLED_BACK; one still running returns 409 IMPORT_STILL_RUNNING (cancel it first). A non-owner/admin key gets the 403 shape from the error section above with the rollback-specific message.

8. Retries are safe — pin writes to an Idempotency-Key

Every mutating endpoint on this page accepts an Idempotency-Key header. Pass a stable, client-generated value and the second delivery of the same request replays the first response — the run is not enqueued twice.

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/run" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Idempotency-Key: mig-twilio-2026-09-14-01" \
  -H "Content-Type: application/json" \
  -d '{ "envelope": "enc:v1:g8K2xQ…", "entities": ["contacts"] }'

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/run" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Idempotency-Key: mig-twilio-2026-09-14-01" \
  -H "Content-Type: application/json" \
  -d '{ "envelope": "enc:v1:g8K2xQ…", "entities": ["contacts"] }'

{
  "data": { "jobId": "job_7a1c4e92b0d3f586", "status": "pending" },
  "meta": { "request_id": "req_importsrun03", "timestamp": "2026-09-14T12:00:02Z" }
}

{
  "data": { "jobId": "job_7a1c4e92b0d3f586", "status": "pending" },
  "meta": { "request_id": "req_importsrun03", "timestamp": "2026-09-14T12:00:02Z" }
}

Same key + same body returns the recorded response with an Idempotency-Replay: true header and the original request_id — no second job. A retry that arrives while the first delivery is still in flight gets the 409 in-flight conflict below; back off and retry it (or simply re-poll GET /imports for the job). Key reuse is scoped per credential + path and held for 24h on 2xx (5 min on 4xx, 30 s on 5xx).

422 — Credentials

Past the generic schema case above, the per-provider credential intakes reject a key that fails the provider’s format rules with the check spelled out in error.details. This fires locally — before any round-trip to the provider — so fix the paste and resend; it never becomes a retryable condition.

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": {
        "field": "apiKey",
        "expected": "a Telnyx V2 API key — starts with 'KEY' followed by 16–128 base62 characters",
        "hint": "paste the full key from the Telnyx portal; whitespace and line breaks break the format check"
      }
    },
    "meta": {
      "request_id": "req_imports422b",
      "timestamp": "2026-09-14T12:00:00Z"
    }
  }

Twilio’s variant gates on accountSid (must match AC + 32 hex) plus a minimum-length authToken; Klaviyo on apiKey starting pk_; MessageBird on a 20–128 character key with an optional live_/test_ prefix. Branch on error.details.field exactly as for the generic schema branch.

409 — In-flight idempotency conflict

The concurrency branch of the Idempotency-Key contract above: the retry beat the original delivery.

  {
    "error": {
      "code": "IDEMPOTENCY_IN_FLIGHT",
      "message": "A request with this Idempotency-Key is still being processed.",
      "status": 409,
      "details": { "idempotency_key": "mig-twilio-2026-09-14-01" }
    },
    "meta": {
      "request_id": "req_imports409a",
      "timestamp": "2026-09-14T12:00:00Z"
    }
  }

Back off and resend with the same key, or poll GET /api/v1/imports for the job the first delivery created. Never rotate to a new key on this branch — a new key starts a second run. Two sibling 409s live on the terminal-side endpoints: IMPORT_NOT_CANCELLABLE (error.details.current_status tells you which terminal status blocked the cancel) and ALREADY_ROLLED_BACK / IMPORT_STILL_RUNNING on rollback. All three are stable states, not retries.

API Reference

All Endpoints

Errors worth branching on