Error Codes

All error responses use the FHIR OperationOutcome format. Each issue entry has severity, code (FHIR IssueType), and diagnostics; errors carrying a Huli catalog code also emit it as structured details.coding (system + code, e.g. "HPB-00101"). Branch on the HTTP status and issue[0].code — those are always present and authoritative. Catalog-coded errors additionally prefix diagnostics with the Huli code, in the form "HPB-XXXXX: <message>", so you can extract the code by splitting on ": ". Treat the prefix and details.coding as best-effort / when-present: some FHIR handlers write an OperationOutcome directly with a plain-text diagnostics, no HPB prefix, and no details, so do not assume every response carries them.

This page is generated from the canonical Huli Public API error catalog — do not edit it directly.

#OperationOutcome format

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "HPB-00101: Validation error"
    }
  ]
}

#HPB errors (Public FHIR API)

#HPB-00101

HTTP 400 — Validation error

Recovery: Check the request body against the FHIR R4 resource schema. Ensure resourceType is present and all required fields are provided.

#HPB-00102

HTTP 404 — Resource not found

Recovery: The resource ID does not exist in your organization. Verify the UUID is correct and belongs to your organization.

#HPB-00103

HTTP 409 — Version conflict

Recovery: Version conflict on update. Re-fetch the resource, apply your changes, and retry. Include the current meta.versionId in your request.

#HPB-00104

HTTP 403 — Insufficient scope

Recovery: Your access token does not include the required scope for this operation. Request a new token with the correct scope — see Scopes.

#HPB-00105

HTTP 429 — Rate limit exceeded

Recovery: You have exceeded a rate limit. Token issuance is capped at 20 requests per minute per IP on /auth/token; resource requests use a separate per-key ceiling (default 60 requests per minute). Read the Retry-After header for the exact delay, then retry.

#HPB-00106

HTTP 401 — Authentication failed

Recovery: Authentication failed. Verify your client assertion JWT: check iss, sub, aud, exp, and signature. Ensure your JWKS endpoint is reachable.

#HPB-00107

HTTP 401 — Authentication failed

Recovery: Your access token has expired (5-minute TTL). Request a new token via POST /auth/token.

#HPB-00108

HTTP 409 — Patient has been merged into another record and cannot accept new clinical data

#HPB-00109

HTTP 409 — Patient is marked as deceased and cannot accept new clinical data

#HPB-00110

HTTP 401 — Inbound webhook authentication failed

#HPB-00122

HTTP 413 — Inbound webhook body exceeds the maximum allowed size

#HPB-00111

HTTP 404 — MedicationRequest not found

#HPB-00112

HTTP 404 — ServiceRequest not found

#HPB-00113

HTTP 400 — ServiceRequest must contain at least one item

#HPB-00114

HTTP 409 — Signed or cancelled prescription cannot be modified

#HPB-00115

HTTP 422 — This service offers multiple specialties; a specialty must be selected to book

#HPB-00116

HTTP 422 — The selected specialty is not offered by this service

#HPB-00117

HTTP 404 — Composition not found

#HPB-00118

HTTP 404 — DocumentReference not found

#HPB-00119

HTTP 413 — Document exceeds the maximum allowed size

#HPB-00120

HTTP 400 — Document content is invalid or its declared type does not match

#HPB-00121

HTTP 429 — Sandbox key volume cap exceeded

#HPB-00123

HTTP 409 — A finalized clinical note cannot be voided

#HPB-00124

HTTP 403 — Production credentials cannot be used from a browser origin; use a sandbox key

#HPB-00135

HTTP 409 — Signed or cancelled service order cannot be modified

#HPB-00136

HTTP 409 — Multi-item service orders are read-only on this surface

#HPB-00137

HTTP 422 — Appointment status transition is not allowed

#HPB-00138

HTTP 409 — Appointment already has an active encounter

#HPB-00139

HTTP 422 — Encounter date is outside the allowed registration window

#HPB-00140

HTTP 422 — Cannot modify a medication request in entered-in-error

#HPB-00141

HTTP 403 — Select a normativa-configured clinic before starting a consultation

#HPB-00142

HTTP 422 — Complete the patient's required normativa data before starting a consultation

#HPB-00143

HTTP 422 — Cannot update an observation in entered-in-error

#HPB-00144

HTTP 422 — Observation.subject cannot be changed on update

#HPB-00145

HTTP 400 — Invalid CURP format

#HPB-00146

HTTP 400 — CURP does not match the entered data

#HPB-00147

HTTP 422 — Mexican organizations must select every place from the Mexican national locality catalog instead of sending free-typed place values

#HPB-00148

HTTP 403 — Organization is blocked

#HPB-00149

HTTP 422 — Surname \

#HULI errors (generic)

These generic error codes are shared across all Huli APIs and may appear in responses when a common platform-level condition is triggered.

#HULI-00001

HTTP 500 — Internal server error

Recovery: An unexpected server error occurred. Retry with exponential backoff. If the problem persists, contact support with the request ID from the response.

#HULI-00002

HTTP 404 — Resource not found

#HULI-00003

HTTP 400 — Bad request

#HULI-00004

HTTP 401 — Unauthorized

Recovery: No valid Bearer token was provided. Include Authorization: Bearer <token> on your request.

#HULI-00005

HTTP 403 — Forbidden

#HULI-00007

HTTP 503 — Service unavailable

Recovery: The service is temporarily unavailable. Retry after a short delay.