Skip to content

Errors

The problem body every failure answers with, the machine codes to switch on, and what each one means you should do.

Every failure answers RFC 9457 problem details with Content-Type: application/problem+json.

{
  "type": "about:blank",
  "title": "Consent Required",
  "status": 409,
  "code": "consent_required",
  "detail": "The patient has no current telehealth consent.",
  "request_id": "iad1::abc123-1757340131234-9f2b7c4a"
}

Switch on code. It is the stable machine string; detail is human text that can be reworded at any time, and title is fixed per code. request_id identifies the one request that failed and is the first thing to quote when you ask for help.

The codes

codeStatusWhat it means
invalid_request400The request is malformed, or a required header is missing
unauthorized401Missing, malformed, expired or revoked credential
forbidden403The credential or the grant does not carry the scope, or a test-only route was called with a live credential
baa_required403The integration has not accepted the agreement currently in force
not_found404No such resource for this integration and organization
conflict409The resource is in a state that will not take this
consent_required409A case was filed without a current telehealth and privacy consent, or a lab order was confirmed without the current lab consents
visit_required409The treatment needs a live video visit in the patient's state
not_available_in_state409No clinician could approve the case in the patient's state
idempotency_conflict409The same Idempotency-Key was reused with a different request
gone410The export expired; its bundle and its file links were deleted together
payload_too_large413The body exceeded 1 MB
rate_limited429Too many requests; a Retry-After header names the wait
internal500A fault on our side
live_not_available501This resource has no live path yet
unavailable503A dependency was unreachable; always safe to retry
lab_panel_unavailable404The lab panel is not one the organization orders
patient_ineligible422The patient's chart lacks what the lab network needs
lab_order_open409The patient already has this lab panel on order
collection_unavailable422The lab collection option is not served at that address
lab_order_not_confirmable409The lab order is not awaiting confirmation
lab_order_required409A clinician requires the lab order; only the clinician waives it
labs_unavailable503Lab ordering is not set up for the organization yet
shipping_state_change_requires_new_intake422The new shipping address is in another state than the patient's
shipping_address_locked409The case is closed, or its order has gone to a pharmacy

Validation failures

A 400 invalid_request from schema validation carries issues, one per field, each addressed by the dotted path that produced it.

{
  "code": "invalid_request",
  "detail": "The request body is invalid.",
  "issues": [
    { "path": "phone", "message": "Must be an E.164 phone number." },
    { "path": "address.postal_code", "message": "Must be a US postal code." }
  ]
}

The six worth handling separately

baa_required is not a permission problem. Somebody signs the agreement in the developer portal and the same credential starts working. Do not retry it.

consent_required is answered by going back to the patient, not by changing the request. Record the missing consent and file the case again.

visit_required means a clinician can decide this treatment in the patient's state only at a live video visit. Book one with POST /v1/visits and send the intake; do not retry the case. detail names the treatment category, the state and that next step.

not_available_in_state means no clinician could approve the case where the patient lives: the patient has no state on file, no clinician is licensed there yet, or the state does not offer a requested treatment. Remove the line detail names, or correct the patient's address. A retry will not succeed. GET /v1/states publishes what each state requires and blocks.

live_not_available means the operation is published and sandboxed but has no live path yet. It is a 501 rather than a 403 so your client does not treat it as something a scope would fix.

idempotency_conflict means you reused a key with a different body. See Rate limits and idempotency.

What to retry

AnswerRetry
429Yes, after Retry-After
500, 502, 503, 504Yes, with backoff
400, 401, 403, 404, 409, 413No; the same request will fail the same way

Retry a write only with the same Idempotency-Key you sent the first time. A write with no key must not be retried, because you cannot tell a timeout from a success.

Both SDKs implement exactly this ladder. See SDKs.

Errors that carry no body

A request to a host that does not serve the path answers 404 with no problem body. api.cuvo.co serves /v1, developers.cuvo.co serves the portal and these docs, and mcp.cuvo.co serves /mcp. Calling /v1 on the docs host is a 404 rather than a quiet cross-serve.