Errors worth branching on

These five failures cover the replay fetch (GET /api/v1/sessionreplay/), every screen-recording view from the dashboard. 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_sessionra1",
      "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_sessionra1f",
      "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": "session_id", "value": "sess_0192", "expected": "a session id from the same tenant (case-sensitive)" }
    },
    "meta": {
      "request_id": "req_sessionrb2",
      "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 the tenant-scoped session id 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_sessionrc3",
      "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.

404 — Not found

  {
    "error": {
      "code": "SESSION_REPLAY_EXPIRED",
      "message": "This replay has been purged under the retention policy.",
      "status": 404,
      "details": { "purged_at": "2026-09-03T11:50:00Z", "retention_days": 14 }
    },
    "meta": {
      "request_id": "req_sessionrd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Surface retention info to the operator — a retry cannot restore the asset.

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.
`SESSION_REPLAY_EXPIRED` (404 not found)	Surface retention info to the operator	Branch on `error.code`. A retry cannot restore the asset.

Violations behind the score

Weights used by the ranked list’s counts and the per-session timeline scoring: rage_click 3, error_click 3, dead_click 2, u_turn 2. A click reports at most one violation — a click that precedes a JS error counts as error_click (not dead_click), and a rage burst consumes its member clicks once. This is what makes the score comparable across sessions: it’s a count of distinct problems, not repeated counting of the same click. The daily triage loop that consumes these weights lives in High-friction sessions: read frustration signals.

Worked request and response samples

Copy a request as written, substitute your own ids, and compare the response envelope. Every example uses the same { data, meta } shape as the error sections above.

List recent recordings

GET /api/v1/session-replay

Each row is a lightweight summary. Use recording_id, playback_token, started_at, and duration_ms to identify a replay; when offloaded is true, fetch the conversation to load the complete event stream.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/session-replay" -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/session-replay', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Python

import os, requests
r = requests.get('https://api.orbit.devotel.io/api/v1/session-replay', headers={'X-API-Key': os.environ['ORBIT_API_KEY']})
print(r.json())

package main
import ("net/http"; "os")
func main() { req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/session-replay", nil); req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY")); http.DefaultClient.Do(req) }

Ruby

require 'net/http'
uri = URI('https://api.orbit.devotel.io/api/v1/session-replay')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
puts Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req).body }

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/session-replay');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "recordings": [
      {
        "conversation_id": "conv_8b2c4d6e1f",
        "recording_id": "sreplay_01J9RSF5GZWZ4TQ0AEXAMPLE",
        "status": "ended",
        "visitor_id": "visitor_01J9R",
        "start_url": "https://shop.example/checkout",
        "started_at": "2026-09-08T11:57:38.000Z",
        "ended_at": "2026-09-08T11:59:42.000Z",
        "duration_ms": 124000,
        "playback_token": "sreplay_token_01J9RSF5GZWZ4TQ0AEXAMPLE",
        "event_count": 842,
        "size_bytes": 284190,
        "truncated": false,
        "offloaded": false,
        "total_event_count": 842,
        "total_size_bytes": 284190
      }
    ]
  },
  "meta": { "request_id": "req_sessionreplay_list", "timestamp": "2026-09-08T12:00:00Z" }
}

Get a recording for playback

GET /api/v1/session-replay/{conversationId}

The response returns the stored replay event stream, not a raw video URL. The list row’s recording_id identifies the same recording; status, timestamps, and event fields describe its playback data.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/session-replay/conv_8b2c4d6e1f" -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/session-replay/conv_8b2c4d6e1f', { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } })
console.log(await res.json())

Python

import os, requests
r = requests.get('https://api.orbit.devotel.io/api/v1/session-replay/conv_8b2c4d6e1f', headers={'X-API-Key': os.environ['ORBIT_API_KEY']})
print(r.json())

package main
import ("net/http"; "os")
func main() { req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/session-replay/conv_8b2c4d6e1f", nil); req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY")); http.DefaultClient.Do(req) }

Ruby

require 'net/http'
uri = URI('https://api.orbit.devotel.io/api/v1/session-replay/conv_8b2c4d6e1f')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
puts Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req).body }

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/session-replay/conv_8b2c4d6e1f');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "session_replay": {
      "recording_id": "sreplay_01J9RSF5GZWZ4TQ0AEXAMPLE",
      "status": "ended",
      "started_at": "2026-09-08T11:57:38.000Z",
      "ended_at": "2026-09-08T11:59:42.000Z",
      "event_count": 842,
      "events": [{ "type": 4, "data": { "source": 0 }, "timestamp": 1757332658000 }]
    }
  },
  "meta": { "request_id": "req_sessionreplay_playback", "timestamp": "2026-09-08T12:00:00Z" }
}

Frustration-signal timeline

GET /api/v1/session-replay/frustration/{conversationId}

Signals are ordered by event time. t_ms is relative to the recording start, so a player can place each marker without exposing event payload details.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/session-replay/frustration/conv_8b2c4d6e1f" -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/session-replay/frustration/conv_8b2c4d6e1f', { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } })
console.log(await res.json())

Python

import os, requests
r = requests.get('https://api.orbit.devotel.io/api/v1/session-replay/frustration/conv_8b2c4d6e1f', headers={'X-API-Key': os.environ['ORBIT_API_KEY']})
print(r.json())

package main
import ("net/http"; "os")
func main() { req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/session-replay/frustration/conv_8b2c4d6e1f", nil); req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY")); http.DefaultClient.Do(req) }

Ruby

require 'net/http'
uri = URI('https://api.orbit.devotel.io/api/v1/session-replay/frustration/conv_8b2c4d6e1f')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
puts Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req).body }

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/session-replay/frustration/conv_8b2c4d6e1f');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "conversation_id": "conv_8b2c4d6e1f",
    "frustration": {
      "score": 8,
      "signals": [
        { "t_ms": 18420, "signal_type": "rage_click", "value": 3 },
        { "t_ms": 42110, "signal_type": "error_click", "value": 1 }
      ]
    }
  },
  "meta": { "request_id": "req_sessionreplay_timeline", "timestamp": "2026-09-08T12:00:00Z" }
}

High-friction ranked list

GET /api/v1/session-replay/frustration/sessions

The list includes only recordings with a score above zero, ordered highest first. Use conversation_id to open the recording and its timeline.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/session-replay/frustration/sessions" -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/session-replay/frustration/sessions', { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } })
console.log(await res.json())

Python

import os, requests
r = requests.get('https://api.orbit.devotel.io/api/v1/session-replay/frustration/sessions', headers={'X-API-Key': os.environ['ORBIT_API_KEY']})
print(r.json())

package main
import ("net/http"; "os")
func main() { req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/session-replay/frustration/sessions", nil); req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY")); http.DefaultClient.Do(req) }

Ruby

require 'net/http'
uri = URI('https://api.orbit.devotel.io/api/v1/session-replay/frustration/sessions')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
puts Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req).body }

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/session-replay/frustration/sessions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "sessions": [
      {
        "conversation_id": "conv_8b2c4d6e1f",
        "recording_id": "sreplay_01J9RSF5GZWZ4TQ0AEXAMPLE",
        "started_at": "2026-09-08T11:57:38.000Z",
        "score": 8,
        "signal_count": 2,
        "counts": { "rage_click": 1, "error_click": 1, "dead_click": 0, "u_turn": 0 }
      }
    ],
    "has_any_recording": true
  },
  "meta": { "request_id": "req_sessionreplay_ranked", "timestamp": "2026-09-08T12:00:00Z" }
}

API Reference

All Endpoints

Errors worth branching on