--- title: 'Error Codes' description: 'Complete reference for all error codes returned by the Huli Public FHIR API.' nav: 'Errors' order: 90 version: v1 source: generated updated: '2026-09-23' --- # Error Codes All error responses use the FHIR [OperationOutcome](https://hl7.org/fhir/R4/operationoutcome.html) 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: "`, 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 ```json { "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "diagnostics": "HPB-00101: Validation error" } ] } ``` ## HPB errors (Public FHIR API) | Code | HTTP Status | Message | |------|-------------|---------| | [HPB-00101](#hpb-00101) | 400 | Validation error | | [HPB-00102](#hpb-00102) | 404 | Resource not found | | [HPB-00103](#hpb-00103) | 409 | Version conflict | | [HPB-00104](#hpb-00104) | 403 | Insufficient scope | | [HPB-00105](#hpb-00105) | 429 | Rate limit exceeded | | [HPB-00106](#hpb-00106) | 401 | Authentication failed | | [HPB-00107](#hpb-00107) | 401 | Authentication failed | | [HPB-00108](#hpb-00108) | 409 | Patient has been merged into another record and cannot accept new clinical data | | [HPB-00109](#hpb-00109) | 409 | Patient is marked as deceased and cannot accept new clinical data | | [HPB-00110](#hpb-00110) | 401 | Inbound webhook authentication failed | | [HPB-00122](#hpb-00122) | 413 | Inbound webhook body exceeds the maximum allowed size | | [HPB-00111](#hpb-00111) | 404 | MedicationRequest not found | | [HPB-00112](#hpb-00112) | 404 | ServiceRequest not found | | [HPB-00113](#hpb-00113) | 400 | ServiceRequest must contain at least one item | | [HPB-00114](#hpb-00114) | 409 | Signed or cancelled prescription cannot be modified | | [HPB-00115](#hpb-00115) | 422 | This service offers multiple specialties; a specialty must be selected to book | | [HPB-00116](#hpb-00116) | 422 | The selected specialty is not offered by this service | | [HPB-00117](#hpb-00117) | 404 | Composition not found | | [HPB-00118](#hpb-00118) | 404 | DocumentReference not found | | [HPB-00119](#hpb-00119) | 413 | Document exceeds the maximum allowed size | | [HPB-00120](#hpb-00120) | 400 | Document content is invalid or its declared type does not match | | [HPB-00121](#hpb-00121) | 429 | Sandbox key volume cap exceeded | | [HPB-00123](#hpb-00123) | 409 | A finalized clinical note cannot be voided | | [HPB-00124](#hpb-00124) | 403 | Production credentials cannot be used from a browser origin; use a sandbox key | | [HPB-00135](#hpb-00135) | 409 | Signed or cancelled service order cannot be modified | | [HPB-00136](#hpb-00136) | 409 | Multi-item service orders are read-only on this surface | | [HPB-00137](#hpb-00137) | 422 | Appointment status transition is not allowed | | [HPB-00138](#hpb-00138) | 409 | Appointment already has an active encounter | | [HPB-00139](#hpb-00139) | 422 | Encounter date is outside the allowed registration window | | [HPB-00140](#hpb-00140) | 422 | Cannot modify a medication request in entered-in-error | | [HPB-00141](#hpb-00141) | 403 | Select a normativa-configured clinic before starting a consultation | | [HPB-00142](#hpb-00142) | 422 | Complete the patient's required normativa data before starting a consultation | | [HPB-00143](#hpb-00143) | 422 | Cannot update an observation in entered-in-error | | [HPB-00144](#hpb-00144) | 422 | Observation.subject cannot be changed on update | | [HPB-00145](#hpb-00145) | 400 | Invalid CURP format | | [HPB-00146](#hpb-00146) | 400 | CURP does not match the entered data | | [HPB-00147](#hpb-00147) | 422 | Mexican organizations must select every place from the Mexican national locality catalog instead of sending free-typed place values | | [HPB-00148](#hpb-00148) | 403 | Organization is blocked | | [HPB-00149](#hpb-00149) | 422 | Surname \ | ### HPB-00101 **HTTP 400** — Validation error **Recovery:** Check the request body against the [FHIR R4 resource schema](https://hl7.org/fhir/R4/). 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](/v1/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. | Code | HTTP Status | Message | |------|-------------|---------| | [HULI-00001](#huli-00001) | 500 | Internal server error | | [HULI-00002](#huli-00002) | 404 | Resource not found | | [HULI-00003](#huli-00003) | 400 | Bad request | | [HULI-00004](#huli-00004) | 401 | Unauthorized | | [HULI-00005](#huli-00005) | 403 | Forbidden | | [HULI-00007](#huli-00007) | 503 | Service unavailable | ### 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 ` 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.