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 — order cannot be charged
`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_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`	A referenced `product_id` does not exist
`product_not_allowed`	`422`	The product exists but is not orderable by this clinic
`rate_limited`	`429`	Per-key write rate limit exceeded
`internal_error`	`500`	Unexpected server failure

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

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