Errors

Every error, on every endpoint, uses the same envelope:

{
  "error": "invalid_request",
  "message": "2 members are missing fields required for enrollment.",
  "details": [
    {
      "index": 3,
      "field": "email",
      "message": "email is required for enrollment"
    },
    {
      "index": 9,
      "field": "lastName",
      "message": "lastName is required for enrollment"
    }
  ]
}

error: a stable, machine-readable code. Branch on this.
message: human-readable; wording may change, so never parse it.
details: present on invalid_request, with one entry per failing field and an index when the payload is an array (census rows, enrollment member checks).

Error codes

Status	Code	Meaning	What to do
400	`invalid_request`	Validation failed; see `details`. A body that is not valid JSON also returns this.	Fix the listed fields and retry.
401	`unauthorized`	Missing, malformed, or revoked API key.	Check the `Authorization: Bearer` header and the key’s status.
403	`live_mode_disabled`	Live key used before live mode is enabled for your account.	Stay on `psk_test_` until the go-live checklist is complete.
403	`forbidden`	Your partner account is suspended, or your partner type or API key can’t call this endpoint (a broker key on an HR-platform endpoint, or the reverse; a narrowed key outside its scope).	Check with your partner engineer. See Broker account setup.
404	`not_found`	No such resource in this mode: test keys can’t see live resources, and `account`, `members`, and `benefits-summary` return 404 until enrollment.	Check the ID, the key’s mode, and the group’s lifecycle stage.
409	`conflict`	The request conflicts with the resource’s current state. See Conflicts.	Read `message`, fetch the resource, and reconcile.
409	`rates_pending`	`POST /quotes` before the census-triggered market comparison has finished.	Wait for `group.market_rates_ready`, or retry with backoff.
410	`quote_expired`	The quote has passed its `expiresAt`.	Create a new quote and retry with its ID.
422	`market_unavailable`	`POST /quotes` when the group’s market cannot be priced: no quotable employees, no platinum PPO, no HSA-eligible PPO, EPO or POS, or the market comparison failed (`group.market_rates_failed`).	Do not retry. Prescience reviews the group.
422	`census_required`	`POST /enrollments` when the census has no active employees to enroll.	`PUT /census` with at least one active employee first.
429	`rate_limited`	Rate limit exceeded. `Retry-After` header included.	Back off per Rate limits.
500	`server_error`	Failure on our side.	Retry with the same `Idempotency-Key` where the endpoint supports one.
503	`not_configured`	A required backing service is unavailable in this environment; we fail closed rather than partially.	Retry with backoff; contact your partner engineer if it persists.

Conflicts

409 conflict covers several states. Its message says which:

The group is already enrolled (creating an embed session or a second enrollment).
The quote is still in_review (POST /enrollments).
A live-mode embed session was requested before Prescience saved your iframe origins.
The employer’s plan terms are not approved yet (GET /benefits-summary).
An enrolled group already exists for this domain (POST /groups).

Request IDs

Every response from the Partner API carries an X-Request-Id header. Log it with every failed call and include it when you contact Prescience; it lets us find the exact request. If you send your own X-Request-Id (up to 128 characters of letters, digits, and simple punctuation), the response echoes it back, so you can correlate our logs with yours. Otherwise, or if your value doesn’t fit that format, Prescience generates a UUID. Treat the value as an opaque string.

HTTP/1.1 409 Conflict
X-Request-Id: 6f1c2a9e-3b7d-4c52-9e8a-1d4f7b20c3a6

{ "error": "rates_pending", "message": "..." }

Handling patterns that hold up

Branch on error; log message and the X-Request-Id header. Codes are contractual; messages aren’t.
Most 409 conflict responses mean the thing already exists or isn’t ready yet. Fetch the resource and continue rather than surfacing an error to the employer.
Retry 500 and 503 with the same Idempotency-Key on the endpoints that honor one. See Rate limits & idempotency.
Don’t blanket-retry 4xx. Other than 429, 409 rates_pending, and the 410 re-quote flow, 4xx errors need a changed request, not a repeated one.

Get Started

Guides

Brokers

Resources

Error codes

Conflicts

Request IDs

Handling patterns that hold up

​Error codes

​Conflicts

​Request IDs

​Handling patterns that hold up

Error codes

Conflicts

Request IDs

Handling patterns that hold up