Errors worth branching on

These five failures cover the session attach (POST /api/v1/cobrowse/sessions//host), on every operator join. 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_cobrowsea1",
      "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_cobrowsea1f",
      "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": "visitor_context", "value": "foo", "expected": "a JSON object (for example, { page: url })" }
    },
    "meta": {
      "request_id": "req_cobrowseb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with a JSON object for visitor_context 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_cobrowsec3",
      "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.

409 — Conflict

  {
    "error": {
      "code": "COBROWSE_SESSION_ALREADY_HOSTED",
      "message": "A host is already attached to this cobrowse session.",
      "status": 409,
      "details": { "host_agent_id": "agent_0192" }
    },
    "meta": {
      "request_id": "req_cobrowsed4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Reconnect the WebSocket instead of re-creating — the session is still live.

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.
`COBROWSE_SESSION_ALREADY_HOSTED` (409 conflict)	Reconnect the WebSocket instead of re-creating	Branch on `error.code`. The session is still live.

SDK surface bridge — End a co-browse session, accept the pending join request, or join for real with the operator’s live key.

These three tabs mirror SDK status and coverage. Python fronts client.request, Go fronts client.Request, and TS fronts fetch-TS — each with the live key.

End the co-browse session

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias" \
  -H "X-API-Key: ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "end"
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "scope": "end"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias", json={
  "scope": "end"
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias", bytes.NewBuffer([]byte(`{
  "scope": "end"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Accept the pending join request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/requests" \
  -H "X-API-Key: ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accept": true
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/requests', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "accept": true
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/requests", json={
  "accept": true
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/requests", bytes.NewBuffer([]byte(`{
  "accept": true
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Alias-wait the join queue

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias/requests" \
  -H "X-API-Key: ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "position": "front"
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias/requests', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "position": "front"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias/requests", json={
  "position": "front"
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias/requests", bytes.NewBuffer([]byte(`{
  "position": "front"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

API Reference

All Endpoints

Errors worth branching on