Errors, retries and request IDs
Handle finite error codes and use safe correlation when asking for support.
Check the status first
Error responses contain a curated code. They do not expose persistence messages or private diagnostics. The generated API reference contains the exact status and code schemas for each operation; use those instead of parsing human-readable text.
| Status | What to do |
|---|---|
400 | Correct the query or UUID; check limit, cursor and supported parameters |
401 | Check the credential, environment, revocation and expiry; do not retry the same credential indefinitely |
403 | Use a key with the required scope |
404 | The resource is absent or inaccessible to this clinic |
408 | The request timed out at admission; retry the read within a bounded policy |
413 | The request exceeded admission limits; correct the request |
429 | Wait for Retry-After before retrying |
503 | The service cannot safely complete the request; retry within a bounded policy |
Retry reads with a bound
v1 contains only GET operations. For transient transport failures, 408, 429 or 503, use a small retry budget with increasing delays and jitter. Honor Retry-After on 429 instead of immediately sending the request again. Stop and surface the failure when the budget is exhausted.
Do not retry 400, 401, 403, 404 or 413 without correcting the underlying condition. A successful empty list is not an error.
Correlate without clinical data
Keep the x-request-id response header with your integration’s safe operation and status metadata. When asking BioParse for support, provide the request ID, API version, approximate time and operation. Do not include a Bearer token, patient name, observation value, source document or raw response body.
Admission errors and API-domain errors can have different finite codes even when they share an HTTP status. Preserve the exact returned code; do not infer a code from the status alone.