Errors worth branching on

These five failures cover the custom-field create (POST /api/v1/custom-fields), which every form-builder save flows through. 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_customfia1",
      "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_customfia1f",
      "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": "name", "value": "Company Size!", "expected": "letters, digits, hyphens and underscores only" }
    },
    "meta": {
      "request_id": "req_customfib2",
      "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 an allowed name (letters/digits/hyphens/underscores) 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_customfic3",
      "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": "CUSTOM_FIELD_NAME_TAKEN",
      "message": "A field with this internal name already exists for the tenant.",
      "status": 409,
      "details": { "existing_field_id": "cf_0192", "existing_name": "Account Size" }
    },
    "meta": {
      "request_id": "req_customfid4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Retry with PATCH against the existing field — do not rename-and-forget.

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.
`CUSTOM_FIELD_NAME_TAKEN` (409 conflict)	Retry with PATCH against the existing field	Branch on `error.code`. Do not rename-and-forget.

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.

Define a custom field

POST /api/v1/custom-fields

Schema-safe extensions to a contact record — the field lands on the explorer once created and honors dependencies. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/custom-fields" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "VIP band",
  "key": "vip_band",
  "type": "select",
  "options": ["gold", "silver"]
}'

{
  "data": {
    "id": "cf_2b6e9d0c1a4f8537",
    "key": "vip_band",
    "type": "select"
  },
  "meta": {
    "request_id": "req_customfields",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Worked sequences — field lifecycle

The blocks below walk one field through its whole life, end to end: define it, list and inspect it in the schema, edit what stays editable, retire it safely, and push values onto contacts. Each sample is a full request or response envelope you can copy; substitute your own ids. The error matrix above stays the branch table for every step.

1 — Define a field (with an enum variant)

The select create above is the common shape. For a closed vocabulary of values, declare type: enum with the allowed values inline in enum_values — values written to contacts are rejected at the door if they are not in the list.

curl -X POST "https://api.orbit.devotel.io/api/v1/custom-fields" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Account status",
  "key": "account_status",
  "type": "enum",
  "enum_values": ["active", "paused", "churned"]
}'

const res = await fetch('https://api.orbit.devotel.io/api/v1/custom-fields', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: 'Account status',
    key: 'account_status',
    type: 'enum',
    enum_values: ['active', 'paused', 'churned'],
  }),
})

201

{
  "data": {
    "id": "cf_2b6e9d0c1a4f8538",
    "name": "Account status",
    "key": "account_status",
    "type": "enum",
    "enum_values": ["active", "paused", "churned"]
  },
  "meta": { "request_id": "req_customfields", "timestamp": "2026-09-08T12:00:00Z" }
}

2 — List the schema and diff one field

List every definition the tenant has, then read one field back for the full validator set. The schema-diff check before a PATCH or DELETE is: GET list → GET {id} → GET {id}/dependencies (blast radius) or {id}/explorer (usage + redacted samples).

curl -X GET "https://api.orbit.devotel.io/api/v1/custom-fields" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const list = await fetch('https://api.orbit.devotel.io/api/v1/custom-fields', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
const { data: fields } = await list.json()

// find the field you are about to change, then diff it
const target = fields.find((f: { key: string }) => f.key === 'account_status')
const detail = await fetch(
  `https://api.orbit.devotel.io/api/v1/custom-fields/${target.id}`,
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } },
)

200

{
  "data": [
    {
      "id": "cf_2b6e9d0c1a4f8537",
      "name": "VIP band",
      "key": "vip_band",
      "type": "select",
      "options": ["gold", "silver"]
    },
    {
      "id": "cf_2b6e9d0c1a4f8538",
      "name": "Account status",
      "key": "account_status",
      "type": "enum",
      "enum_values": ["active", "paused", "churned"]
    }
  ],
  "meta": { "request_id": "req_customfields_list", "timestamp": "2026-09-08T12:00:00Z" }
}

3 — Update what is editable; skip what is immutable

PATCH rewrites the label, description, options, default value, the required / searchable flags, and validators (validator_regex, min_len, max_len, enum_values). The key and type are frozen — send them in the body and they are ignored; a rename of values already stored on contacts is how you orphan data. Passing null for a validator or default_value clears it.

curl -X PATCH "https://api.orbit.devotel.io/api/v1/custom-fields/cf_2b6e9d0c1a4f8537" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "VIP band (revoked-safe)",
  "options": ["gold", "silver", "platinum"],
  "required": true,
  "default_value": null
}'

const res = await fetch('https://api.orbit.devotel.io/api/v1/custom-fields/cf_2b6e9d0c1a4f8537', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: 'VIP band (revoked-safe)',
    options: ['gold', 'silver', 'platinum'],
    required: true,
    default_value: null,
  }),
})

200

{
  "data": {
    "id": "cf_2b6e9d0c1a4f8537",
    "name": "VIP band (revoked-safe)",
    "key": "vip_band",
    "type": "select",
    "options": ["gold", "silver", "platinum"],
    "required": true,
    "default_value": null
  },
  "meta": { "request_id": "req_customfields_patch", "timestamp": "2026-09-08T12:00:00Z" }
}

The key (vip_band) and type (select) come back unchanged — that is your confirmation the immutable pair survived the PATCH.

4 — Retire a field: dependency gate, then force-delete

DELETE is the archive path. Run it without force first: if any segment, campaign, drip enrollment, or flow still references the field you get a 409 carrying the full dependency snapshot — that is the undo-safe version of the call, nothing was removed. Once the dependents are cleaned up (or deliberately abandoned), re-send with ?force=true; dependents are flagged broken and the definition plus every stored value is stripped from contacts.

curl -X DELETE "https://api.orbit.devotel.io/api/v1/custom-fields/cf_2b6e9d0c1a4f8537" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "error": {
    "code": "CUSTOM_FIELD_IN_USE",
    "message": "The field is still referenced by a segment, campaign, or flow.",
    "status": 409,
    "details": {
      "segments": [{ "id": "seg_01J8", "name": "Gold tier customers" }],
      "campaigns": [],
      "flows": [],
      "drip_enrollments": 0
    }
  },
  "meta": { "request_id": "req_customfields_del_guard", "timestamp": "2026-09-08T12:00:00Z" }
}

curl -X DELETE "https://api.orbit.devotel.io/api/v1/custom-fields/cf_2b6e9d0c1a4f8537?force=true" \
  -H "X-API-Key: dv_live_sk_your_key_here"

204 No Content — the field is archived and its key stripped from every contact.

5 — Backfill a segment, then read it back through Contacts

Values land on a contact through PUT /api/v1/custom-fields/values, one field per call, validated against the definition. Backfill a segment by iterating contact ids — the same call idempotent per contact — and confirm the write by reading the contact back through GET /api/v1/contacts/{id}.

curl -X PUT "https://api.orbit.devotel.io/api/v1/custom-fields/values" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "con_8f2a1c9d",
  "key": "account_status",
  "value": "active"
}'

const put = await fetch('https://api.orbit.devotel.io/api/v1/custom-fields/values', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ contact_id: 'con_8f2a1c9d', key: 'account_status', value: 'active' }),
})
const { data: { ok } } = await put.json()
if (!ok) throw new Error('backfill write rejected')

// read back through the contacts surface
const contact = await fetch('https://api.orbit.devotel.io/api/v1/contacts/con_8f2a1c9d', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
const { data } = await contact.json()
console.log(data.custom_attributes.account_status) // 'active'

200 — write accepted

{
  "data": { "contact_id": "con_8f2a1c9d", "key": "account_status", "ok": true },
  "meta": { "request_id": "req_customfields_val", "timestamp": "2026-09-08T12:00:00Z" }
}

200 — read-back through Contacts

{
  "data": {
    "id": "con_8f2a1c9d",
    "name": "Amina Diallo",
    "custom_attributes": { "account_status": "active" }
  },
  "meta": { "request_id": "req_contacts_read", "timestamp": "2026-09-08T12:00:00Z" }
}

For a bulk segment backfill, run the PUT per contact id; a rejected value returns 422 with error.details.field set to the failing key, matching the 422 branch in the matrix above.

API Reference

All Endpoints

Errors worth branching on