Errors worth branching on

curl -X POST https://api.orbit.devotel.io/api/v1/frequency-caps \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "scope": "channel",
    "window_seconds": 86400,
    "max_count": 3,
    "applies_to_categories": ["marketing"],
    "enabled": true
  }'

{
  "data": {
    "id": "fc_0192",
    "organization_id": "org_0192",
    "channel": "sms",
    "scope": "channel",
    "window_seconds": 86400,
    "max_count": 3,
    "applies_to_categories": ["marketing"],
    "enabled": true,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_cap_create",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/frequency-caps \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "scope": "channel",
    "window_seconds": 86400,
    "max_count": 3,
    "applies_to_categories": ["marketing"],
    "enabled": true
  }'

{
  "data": {
    "id": "fc_0192",
    "organization_id": "org_0192",
    "channel": "sms",
    "scope": "channel",
    "window_seconds": 86400,
    "max_count": 3,
    "applies_to_categories": ["marketing"],
    "enabled": true,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_cap_create",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

Worked request and response samples

Create a channel-scoped rule for single-channel throttling; create global when sends across channels share one quota; flip enabled to pause without deleting. The 422 object below points to window_seconds (one of the two fields readers most often mis-type), while the rule matrix below informs retry/discipline for the rest.

POST /api/v1/frequency-caps

curl -X POST https://api.orbit.devotel.io/api/v1/frequency-caps \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "scope": "channel",
    "window_seconds": 86400,
    "max_count": 3,
    "applies_to_categories": ["marketing"],
    "enabled": true
  }'

{
  "data": {
    "id": "fc_0192",
    "organization_id": "org_0192",
    "channel": "sms",
    "scope": "channel",
    "window_seconds": 86400,
    "max_count": 3,
    "applies_to_categories": ["marketing"],
    "enabled": true,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_cap_create",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

window_seconds (60–2,592,000) names the rolling window; scope: "channel" counts one channel per contact while scope: "global" aggregates sends across every channel into one counter (use channel: "*"). applies_to_categories: null (or the field omitted) applies the rule to every category. Update via PATCH /api/v1/frequency-caps/{id}; disable with enabled: false to pause without deleting.

These five failures cover the frequency-cap upsert (POST /api/v1/frequency-caps), saved from every quiet-hours form. 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_frequenca1",
      "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_frequenca1f",
      "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": "window", "value": "hourly", "expected": "one of minute, hour, day, week" }
    },
    "meta": {
      "request_id": "req_frequencb2",
      "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 one of minute, hour, day, week for the window 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_frequencc3",
      "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": "CAP_CONFLICTING_RULE",
      "message": "This cap overlaps an existing rule for the same scope and channel.",
      "status": 409,
      "details": { "conflicting_rule_id": "cap_0192" }
    },
    "meta": {
      "request_id": "req_frequencd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Patch the existing rule or narrow the scope — a retry creates no new rule.

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.
`CAP_CONFLICTING_RULE` (409 conflict)	Patch the existing rule or narrow the scope	Branch on `error.code`. A retry creates no new rule.

API Reference

All Endpoints

Errors worth branching on

Worked request and response samples