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
code | Status | What it means |
|---|---|---|
invalid_request | 400 | The request is malformed, or a required header is missing |
unauthorized | 401 | Missing, malformed, expired or revoked credential |
forbidden | 403 | The credential or the grant does not carry the scope, or a test-only route was called with a live credential |
baa_required | 403 | The integration has not accepted the agreement currently in force |
not_found | 404 | No such resource for this integration and organization |
conflict | 409 | The resource is in a state that will not take this |
consent_required | 409 | A case was filed without a current telehealth and privacy consent, or a lab order was confirmed without the current lab consents |
visit_required | 409 | The treatment needs a live video visit in the patient's state |
not_available_in_state | 409 | No clinician could approve the case in the patient's state |
idempotency_conflict | 409 | The same Idempotency-Key was reused with a different request |
gone | 410 | The export expired; its bundle and its file links were deleted together |
payload_too_large | 413 | The body exceeded 1 MB |
rate_limited | 429 | Too many requests; a Retry-After header names the wait |
internal | 500 | A fault on our side |
live_not_available | 501 | This resource has no live path yet |
unavailable | 503 | A dependency was unreachable; always safe to retry |
lab_panel_unavailable | 404 | The lab panel is not one the organization orders |
patient_ineligible | 422 | The patient's chart lacks what the lab network needs |
lab_order_open | 409 | The patient already has this lab panel on order |
collection_unavailable | 422 | The lab collection option is not served at that address |
lab_order_not_confirmable | 409 | The lab order is not awaiting confirmation |
lab_order_required | 409 | A clinician requires the lab order; only the clinician waives it |
labs_unavailable | 503 | Lab ordering is not set up for the organization yet |
shipping_state_change_requires_new_intake | 422 | The new shipping address is in another state than the patient's |
shipping_address_locked | 409 | The 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
| Answer | Retry |
|---|---|
| 429 | Yes, after Retry-After |
| 500, 502, 503, 504 | Yes, with backoff |
| 400, 401, 403, 404, 409, 413 | No; 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.