Documentation Index
Fetch the complete documentation index at: https://docs.have-foresight.app/llms.txt
Use this file to discover all available pages before exploring further.
When a request fails, the API returns a non-2xx HTTP status and a JSON body
in this shape:
{
"error": {
"type": "validation_error",
"code": "missing_required_field",
"message": "Field `patientId` is required.",
"param": "patientId",
"requestId": "req_01J5KA3XQR9V2W4Y6Z8B0D2F4H",
"docsUrl": "https://docs.have-foresight.app/guides/errors#missing_required_field"
}
}
| Field | Description |
|---|
type | High-level category. One of authentication_error, permission_error, validation_error, not_found_error, conflict_error, rate_limit_error, payer_error, server_error. |
code | Machine-readable specific code. Stable across versions; safe to switch on. |
message | Human-readable explanation, suitable for surfacing to engineers (not end users). |
param | Optional. The request field that caused the validation failure. |
requestId | Echoed in logs and metrics. Include this in any support ticket. |
docsUrl | Deep link to this guide for the specific code. |
How to handle errors
| Status | Action |
|---|
400 | Fix the request body and retry. Do not retry without changes. |
401 | Check X-API-Key. Do not retry until credentials are fixed. |
403 | The key is valid but lacks scope or organization access. Do not retry without permission changes. |
404 | The resource doesn’t exist or your org can’t see it. Do not retry. |
409 | Re-read the resource and reconcile. For idempotency conflicts, use a fresh Idempotency-Key. |
422 | Business-rule violation (e.g. submitting a claim with no service lines). Inspect message/code. |
429 | Wait Retry-After seconds, then retry. See Rate limits. |
5xx | Retry with exponential backoff. If the failure persists past 3 retries, escalate. |
Common error codes
Authentication
| Code | Description |
|---|
missing_api_key | No X-API-Key or Authorization header present. |
invalid_api_key | Key format invalid, revoked, or unknown. |
expired_api_key | Key passed its expiration date. |
forbidden_scope | Key lacks the scope this endpoint requires. |
organization_mismatch | Resource belongs to a different organization. |
Validation
| Code | Description |
|---|
missing_required_field | A required field was absent. param indicates which. |
invalid_field_type | Wrong type (e.g. string for an integer cents field). |
invalid_enum_value | Value not in the allowed enum set. |
invalid_uuid_format | A field requires a UUID and the value isn’t one. |
invalid_date_format | Date or date-time isn’t ISO 8601. |
invalid_currency_amount | Monetary value wasn’t an integer (cents). |
field_value_too_long | String exceeds the field’s max length. |
cross_field_constraint | Two or more fields violate a constraint together (e.g. dischargeDate before admissionDate). |
Resource
| Code | Description |
|---|
resource_not_found | Resource ID is well-formed but doesn’t exist. |
resource_already_exists | Unique constraint violation on create. |
resource_deleted | Resource exists but has been soft-deleted. |
Idempotency
| Code | Description |
|---|
idempotency_key_in_use | An identical key is mid-flight. Wait and retry. |
idempotency_key_mismatched_body | Same key, different request body. Use a fresh key. |
Rate limits
| Code | Description |
|---|
rate_limit_exceeded | You exceeded your tier’s RPS or daily quota. Honor Retry-After. |
Payer / clearinghouse
| Code | Description |
|---|
payer_unavailable | Payer or clearinghouse returned an error or timed out. |
payer_invalid_response | Payer responded but the response was malformed. |
payer_rejected | Payer accepted the message and rejected it (e.g. 277CA). |
Server
| Code | Description |
|---|
internal_error | Unexpected server error. Retry with backoff. Include requestId. |
service_unavailable | A required downstream is degraded. Retry with backoff. |
Retry strategy
For 429 and 5xx, retry with exponential backoff and jitter:
attempt 1: wait Retry-After (or 1s if absent)
attempt 2: wait min(2s + jitter, Retry-After)
attempt 3: wait min(4s + jitter, Retry-After)
attempt 4+: escalate, do not retry indefinitely
4xx errors (other than 409 idempotency conflicts and 429) should
not be retried — they indicate a client mistake that won’t resolve
itself.
Reporting an error
When opening a support ticket, always include the requestId from the
error envelope. We can pull the full request and downstream traces from
that ID alone.