Errors worth branching on

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/agent-mandate \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "mnd_checkout_0042",
    "agentId": "agent_openai_checkout",
    "principalId": "usr_0192",
    "maxPerTransaction": 49.99,
    "totalCap": 199.99,
    "currency": "USD",
    "allowedMerchants": ["acme-coffee"],
    "expiresAt": 1780012800,
    "reference": "checkout-0042"
  }'

{
  "data": {
    "id": "mnd_checkout_0042",
    "agentId": "agent_openai_checkout",
    "principalId": "usr_0192",
    "maxPerTransaction": 49.99,
    "totalCap": 199.99,
    "currency": "USD",
    "allowedMerchants": ["acme-coffee"],
    "spent": 0,
    "authorizationCount": 0,
    "status": "active",
    "expiresAt": 1780012800,
    "createdAt": 1780009859
  },
  "meta": {
    "request_id": "req_commerce_issue",
    "timestamp": "2026-09-11T12:00:01Z"
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/agent-mandate \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "mnd_checkout_0042",
    "agentId": "agent_openai_checkout",
    "principalId": "usr_0192",
    "maxPerTransaction": 49.99,
    "totalCap": 199.99,
    "currency": "USD",
    "allowedMerchants": ["acme-coffee"],
    "expiresAt": 1780012800,
    "reference": "checkout-0042"
  }'

{
  "data": {
    "id": "mnd_checkout_0042",
    "agentId": "agent_openai_checkout",
    "principalId": "usr_0192",
    "maxPerTransaction": 49.99,
    "totalCap": 199.99,
    "currency": "USD",
    "allowedMerchants": ["acme-coffee"],
    "spent": 0,
    "authorizationCount": 0,
    "status": "active",
    "expiresAt": 1780012800,
    "createdAt": 1780009859
  },
  "meta": {
    "request_id": "req_commerce_issue",
    "timestamp": "2026-09-11T12:00:01Z"
  }
}

Worked request and response samples

POSTing a charge requires an issued mandate. Issue the mandate first, post the charge against its id, then handle the authorize round-trip the endpoint’s gateway needs. The envelope below nests two objections: mandate id formatting (422 VALIDATION_ERROR) and replay credit protection (409 COMMERCE_MANDATE_ALREADY_SPENT). Steps 1 and 2 below are the frame that avoids both.

1. Issue the mandate

POST /api/v1/commerce/agent-mandate

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/agent-mandate \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "mnd_checkout_0042",
    "agentId": "agent_openai_checkout",
    "principalId": "usr_0192",
    "maxPerTransaction": 49.99,
    "totalCap": 199.99,
    "currency": "USD",
    "allowedMerchants": ["acme-coffee"],
    "expiresAt": 1780012800,
    "reference": "checkout-0042"
  }'

{
  "data": {
    "id": "mnd_checkout_0042",
    "agentId": "agent_openai_checkout",
    "principalId": "usr_0192",
    "maxPerTransaction": 49.99,
    "totalCap": 199.99,
    "currency": "USD",
    "allowedMerchants": ["acme-coffee"],
    "spent": 0,
    "authorizationCount": 0,
    "status": "active",
    "expiresAt": 1780012800,
    "createdAt": 1780009859
  },
  "meta": {
    "request_id": "req_commerce_issue",
    "timestamp": "2026-09-11T12:00:01Z"
  }
}

The mandate snapshot — every field the wire round-trips mandate carries on the authorize/charge body — is this data. Hold it; every subsequent endpoint that touches a charge sends it back verbatim so the consent digest re-verifies before spend.

2. Dry-run authorize, then charge

POST /api/v1/commerce/agent-mandate/authorize — same shape the charge endpoint accepts; /charge commits the spend (returns charge and the updated mandate), /authorize checks the digest and allowance without committing. /authorize answers authorized: true | false because a mandate either passes or returns intentional detail ahead of the final call.

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mandate": { "id": "mnd_checkout_0042", "agentId": "agent_openai_checkout", "principalId": "usr_0192", "maxPerTransaction": 49.99, "totalCap": 199.99, "currency": "USD", "allowedMerchants": ["acme-coffee"], "spent": 0, "authorizationCount": 0, "status": "active", "consentDigest": "dg_0192", "expiresAt": 1780012800, "createdAt": 1780009859, "updatedAt": 1780009859, "revokedAt": null },
    "charge": { "amount": 24.5, "currency": "USD", "merchant": "acme-coffee", "reference": "checkout-0042" }
  }'

{
  "data": {
    "authorized": true,
    "mandate": {
      "id": "mnd_checkout_0042",
      "authorizationCount": 1,
      "spent": 0,
      "status": "active"
    }
  },
  "meta": {
    "request_id": "req_commerce_authorize",
    "timestamp": "2026-09-11T12:00:04Z"
  }
}

Next call POST /api/v1/commerce/agent-mandate/charge with the same body to commit the charge, or POST /api/v1/commerce/agent-mandate/revoke to invalidate the mandate before expiry. COMMERCE_MANDATE_ALREADY_SPENT below only fires when the same replay-protection reference spends twice — a client that always authorizes then charges once per mandate never pays the 409 tax.

These five failures cover the charge create (POST /api/v1/commerce/charges), which one-tap checkout fires per order. 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_commercea1",
      "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_commercea1f",
      "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": "mandate_id", "value": "mnd", "expected": "the full mandate id, formatted as mnd_<24-chars>" }
    },
    "meta": {
      "request_id": "req_commerceb2",
      "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 full mandate 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_commercec3",
      "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": "COMMERCE_MANDATE_ALREADY_SPENT",
      "message": "This mandate's allowance was already committed against an earlier charge.",
      "status": 409,
      "details": { "mandate_id": "mnd_0192" }
    },
    "meta": {
      "request_id": "req_commerced4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Treat as idempotent-replay protection — return the original receipt instead of re-charging.

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.
`COMMERCE_MANDATE_ALREADY_SPENT` (409 conflict)	Treat as idempotent-replay protection	Branch on `error.code`. Return the original receipt instead of re-charging.

API Reference

All Endpoints

Errors worth branching on

Worked request and response samples

1. Issue the mandate

2. Dry-run authorize, then charge