Errors worth branching on

curl -X POST https://api.orbit.devotel.io/api/v1/reports/generate \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "range": "30d" }'

{
  "data": {
    "channel": "sms",
    "from": "2026-08-12T00:00:00.000Z",
    "to": "2026-09-11T00:00:00.000Z",
    "summary": {
      "total": 1521,
      "sent": 1489,
      "delivered": 1420,
      "submitted_no_receipt": 31,
      "failed": 69,
      "queued": 14,
      "delivery_rate": 0.9532,
      "chargeable_count": 1489,
      "avg_cost": 0.0084,
      "total_cost": 12.51
    },
    "daily": [ { "date": "2026-09-10", "sent": 54 }, { "date": "2026-09-11", "sent": 12 } ],
    "by_channel": [ { "channel": "sms", "total": 1521 } ]
  },
  "meta": {
    "request_id": "req_report_generate",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/reports/generate \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "range": "30d" }'

{
  "data": {
    "channel": "sms",
    "from": "2026-08-12T00:00:00.000Z",
    "to": "2026-09-11T00:00:00.000Z",
    "summary": {
      "total": 1521,
      "sent": 1489,
      "delivered": 1420,
      "submitted_no_receipt": 31,
      "failed": 69,
      "queued": 14,
      "delivery_rate": 0.9532,
      "chargeable_count": 1489,
      "avg_cost": 0.0084,
      "total_cost": 12.51
    },
    "daily": [ { "date": "2026-09-10", "sent": 54 }, { "date": "2026-09-11", "sent": 12 } ],
    "by_channel": [ { "channel": "sms", "total": 1521 } ]
  },
  "meta": {
    "request_id": "req_report_generate",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

Worked request and response samples

The {id}/run → {id}/download/{run_id} pair the scheduler walks is an artifact cycle: a /run call kicks off a report run (out-of-band generation), then a /download call retrieves its output once status: ready flips. The ad-hoc POST /api/v1/reports/generate below gives the same data in one request — use run when persistence matters, generate for dashboard drilldowns.

POST /api/v1/reports/generate — aggregate metrics + daily + per-channel breakdowns in one envelope

curl -X POST https://api.orbit.devotel.io/api/v1/reports/generate \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "range": "30d" }'

{
  "data": {
    "channel": "sms",
    "from": "2026-08-12T00:00:00.000Z",
    "to": "2026-09-11T00:00:00.000Z",
    "summary": {
      "total": 1521,
      "sent": 1489,
      "delivered": 1420,
      "submitted_no_receipt": 31,
      "failed": 69,
      "queued": 14,
      "delivery_rate": 0.9532,
      "chargeable_count": 1489,
      "avg_cost": 0.0084,
      "total_cost": 12.51
    },
    "daily": [ { "date": "2026-09-10", "sent": 54 }, { "date": "2026-09-11", "sent": 12 } ],
    "by_channel": [ { "channel": "sms", "total": 1521 } ]
  },
  "meta": {
    "request_id": "req_report_generate",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

The 422 envelope below marks error.details.field — the generate body fields are channel, range (24h/7d/30d/90d), from, to; branch there and never blind-retry. Response headers name Idempotency-Key for timeouts under load — retry same key replays the original 200 instead of re-charging the compute.

These five failures cover the artifact cycle outlined above (/reports/{id}/run → /reports/{id}/download/{run_id}), plus the ad-hoc /reports/generate the worked sample uses. 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_reportsa1",
      "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_reportsa1f",
      "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": "range", "value": "31d", "expected": "one of 24h | 7d | 30d | 90d, or an explicit from/to pair" }
    },
    "meta": {
      "request_id": "req_reportsb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the generate body did not match the request schema — branch on error.details.field; the accepted values live above (channel enum, range shortcut, or an explicit from/to pair) and a blind retry repeats the same 422.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_reportsc3",
      "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": "REPORTS_NOT_ENABLED",
      "message": "Scheduled reports are not enabled for this organization.",
      "status": 402
    },
    "meta": {
      "request_id": "req_reportsd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Surface the upsell page — the report route is data-safe; only provisioning gates it.

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.
`REPORTS_NOT_ENABLED` (402 feature gate)	Surface the upsell page	Branch on `error.code`. The report route is data-safe; only provisioning gates it.

API Reference

All Endpoints

Errors worth branching on

Worked request and response samples