Errors

Every failure returns a standard HTTP status code and a consistent JSON envelope.

Error envelope

{
  "error": {
    "code": "validation_failed",
    "message": "items[0].quantity must be a positive integer"
  }
}

code is stable and machine-readable — branch on it. message is human-readable and may change.

Error codes

`code`	Status	Meaning
`invalid_body`	`400`	Body is missing, not JSON, or structurally unreadable
`unauthorized`	`401`	Key is missing, malformed, revoked, or expired
`card_required`	`402`	No card on file for the clinic — a `card_on_file` order cannot be charged (not applicable to `patient_checkout`)
`payment_declined`	`402`	The clinic’s card on file was declined
`insufficient_scope`	`403`	Key lacks the scope this endpoint requires
`not_vita_clinic`	`403`	Write endpoint called by an org that is not an active Vita Clinic
`not_available`	`403`	A Partner API endpoint was called by an organization it isn’t available to (for example, invites need a rep account)
`not_found`	`404`	Resource does not exist or belongs to another organization
`patient_not_found`	`404`	Referenced patient does not exist for this organization
`duplicate_request`	`409`	Idempotency conflict — the external id is in use with a different payload
`validation_failed`	`422`	Well-formed JSON that failed field validation
`product_not_found`	`422` or `404`	A referenced `product_id` does not exist (or, in the Partner API store, is not a product you can sell)
`product_not_allowed`	`422`	The product exists but is not orderable by this clinic
`bundle_has_services`	`422`	A package line includes a clinic service and can’t be ordered through the API — see Packages, pricing and checkout
`store_not_available`	`403`	The Partner API store isn’t enabled for this account yet, see Partner API
`price_below_cost`	`422`	`price_cents` is below VitaRelay’s price for the product
`product_not_listed`	`422`	An order line is for a product you haven’t listed with `PUT /store/products/{product_id}`
`product_unavailable`	`422`	A wholesale order line is not on the research catalog or not available to your organization
`attestation_required`	`422`	The buyer must confirm all three attestation boxes
`order_not_found`	`404`	No store order with that id
`order_not_payable`	`409`	The order isn’t awaiting payment
`pricing_not_enabled`	`403`	`pricing` was sent on an invite but setting your own pricing isn’t enabled for your organization
`unknown_rep_partner`	`422`	`on_behalf_of` isn’t the organization id of a Rep Partner in your network
`no_payment_method`	`402`	A Partner API wholesale order needs a default card on file, see Partner API
`card_declined`	`402`	The card was declined; try another card on the same order
`invite_not_found`	`404`	No invite with that id belongs to your organization, see Partner API
`invite_expired`	`409`	The invite expired; its product list can no longer be changed. Create a new invite
`invite_already_accepted`	`409`	The invite was already accepted and can no longer be revoked, see Partner API
`card_form_unavailable`	`503`	The card form (Accept.js keys) is not available right now; retry shortly, see `GET /payment-methods/config`
`bundle_not_priced`	`422`	A package can’t be priced (empty, unpriced member, or package price too low)
`purchase_mode_not_allowed`	`422`	The item isn’t offered in that purchase mode (for example a one-time purchase of a subscription-only item)
`invalid_id`	`400`	A path id isn’t a valid UUID (and wasn’t a known `external_patient_id`)
`consult_first_not_available`	`409` or `422`	Consult-first checkout isn’t turned on for this clinic, or it can’t be used for this order (for example no doctor consult applies), see `POST /consult-requests`
`intake_required`	`422`	The patient’s intake (or bloodwork for a hormone item) isn’t complete, so a consult can’t be taken yet
`product_not_priced`	`422`	A requested item isn’t priced in the clinic’s patient shop
`request_rejected`	`422`	The consult request can’t be placed; the `message` says why
`no_acting_account`	`422`	The key has no account to place the request under (the patient has no login and the key has no creator)
`not_awaiting_approval`	`409`	The consult request isn’t waiting for the patient’s approval
`payment_method_not_found`	`402`	The `payment_method_id` isn’t a card saved to this patient
`card_not_saved`	`402`	The new card could not be saved; try again or use another card
`bad_request`	`400`	A query parameter or catalog id is malformed (for example `page` must be an integer ≥ 1)
`intake_required`	`422`	The patient has no submitted intake yet — complete one first (Intakes and prescriber review)
`order_rejected`	`422`	The order was refused by the ordering rules (the `message` says why: an unavailable item, a prescription rule, shipping) — nothing was created
`shipping_required`	`422`	The order ships something but no shipping address was supplied or stored on the patient
`invalid_cadence`	`422`	A subscription cadence isn’t `weekly`, `monthly` or `quarterly`, or one is required and missing
`membership_required`	`403`	`POST /v1/orders` for a patient who does not hold an active BBX Membership (BBX accounts only). Start the membership first, then retry
`unsupported_line`	`422`	A one-time custom service line — services are bought by the patient in your storefront
`not_chargeable`	`422`	`POST /orders/{id}/pay` on an order with no amount due
`duplicate_prescription`	`409`	An active eScript already exists for this patient and drug
`prescriber_not_found` / `prescriber_not_licensed` / `patient_state_missing`	`422`	Prescription rules (doctor-network keys): unknown prescriber, no licence for the patient’s state, or no state on the patient
`not_idn`	`403`	An endpoint restricted to the Internal Doctor Network was called by another organization
`card_not_saved`	`422`	The gateway couldn’t save the card — ask the patient to re-enter it
`payment_method_required`	`422`	A subscription line needs the patient’s saved card (`payment_method_id`)
`rate_limited`	`429`	Per-key write rate limit exceeded
`internal_error`	`500`	Unexpected server failure
`payment_unavailable`	`503`	Card checkout (`billing_mode=patient_checkout`) is temporarily unavailable — nothing was created, retry later
`integration_paused`	`503`	The doctor-network integration is paused, so an inbound prescription was not stored; the sender should resend it once the integration is back on

Notable cases

rate_limited — the response carries Retry-After and X-RateLimit-* headers. See Rate Limits.
card_required / payment_declined — the order was validated but not created as paid. Fix the card on file and retry with the same external_order_id; the request is idempotent.
duplicate_request — you reused an external id with a different body. Replaying the same body is not an error: it returns the original record with 200 instead of 201.
not_found vs patient_not_found — resources outside your organization are reported as missing, never as forbidden.

Handling errors in code

const res = await fetch("https://vitarelay.com/api/public/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VITARELAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

if (!res.ok) {
  const { error } = await res.json();

  switch (error.code) {
    case "rate_limited":
      // back off using the Retry-After header, then retry
      break;
    case "card_required":
    case "payment_declined":
      // surface a billing problem to the clinic
      break;
    default:
      console.error(`VitaRelay error [${res.status}] ${error.code}: ${error.message}`);
  }
}

5xx errors

An internal_error means the request did not complete. It is safe to retry with exponential backoff — include your external id so the retry is idempotent. Contact info@vitarelay.com if failures persist.

Getting Started

API Reference

Webhooks

Guides

Errors

Errors

Error envelope

Error codes

Notable cases

Handling errors in code

5xx errors

​Errors

​Error envelope

​Error codes

​Notable cases

​Handling errors in code

​5xx errors

Errors

Error envelope

Error codes

Notable cases

Handling errors in code

5xx errors