Error Handling

The API will always return sensible HTTP status code.

There are 2 types of API errors:

  • 400 series status codes for client issues
  • 500 series status codes for server issues.

Common HTTP Status codes returned on errors:

  • 400 Bad Request - search could not be processed or failed basic FHIR validation rules
  • 401 Not Authorized - authorization is required for the interaction that was attempted
  • 404 Not Found - resource type not supported, or not a FHIR end-point
  • 422 Unprocessable Entity - resource was rejected by the server because it "violated applicable FHIR profiles or server business rules"
  • 500 - Internal Server Error

Along with the Status Code the API will return an OperationOutcome resource as response containing details about the error. Here is an example of OperationOutcome object:

   "resourceType": "OperationOutcome",
   "issue": [
"severity": "error",
           "code": "processing",
           "diagnostics": "Invalid request: The FHIR endpoint on this server does not know how to handle GET operation[Patient] with parameters [[wrong_parameter]]"

Table of Error Messages

This table contains common error codes and error messages.

Status CodeMessageComments/Solutions
400No error messageCheck the endpoint that has been called. Look for extra characters such as 2 slashes, or incomplete endpoint URL.
400This operations can be executed in asynchronous mode only...Some operations in Health Gorilla can take significant time to complete and must be done asynchronously. More detail can be found in the Async section
400Subject validation failedWhen calling the Oauth endpoint, a check is done against the sub in the JWT. This message indicates the subject is not a valid user or the Oauth client is not bound to the tenant containing the user. Check the credentials to insure the subject in the JWT is correct.
400Invalid RequestThe syntax of the call is incorrect.
401Invalid TokenThe access token used in the header.Authorization field is not valid.
403Insufficient access rights to perform the operationThis is usually caused by a user attempting to call an incorrect version of FHIR not associated with their Oauth client. Insure the correct FHIR version URL is being called.
STU3 = /fhir/resourceName
R4 = /fhir/R4/resourceName
403Tenant has no license to execute this method.User is trying to access an API method that is not licensed for their tenant.
404Not foundThe resource being searched for cannot be found. This could mean the resource ID is incorrect or does not exist in the current tenant.
404rejected_www-requestUser is trying to call the API's using the www domain in the URL. Correct API domain is
405method not allowedThe method being used (PUT, POST, GET) is not allowed on the API being called.
415no error messageUsually occurs due to an unsupported media type being uploaded.
422Case specifica 422 will contain a specific message describing the error in the payload being sent to Health Gorilla. Examples: Missing content, required fields missing, invalid format in some fields, etc.
422Record with supplied ID2 already existsMRN must be unique within a user's tenant. This error means a patient is being created with an external MRN that has already been associated with an existing patient in the tenant.
422Empty content attachment suppliedOccurs when a DocumentReference is posted without an attachment.
422Supplied record duplicates the existing one.;Failed to create duplicateThe resource being created is considered a duplicate based on Health Gorilla's deduplication logic.
422Supplied performer is unknownWhen placing a lab order via the RequestGroup API, the lab vendor the user included is empty or not valid.
422Supplied AuthorizedBy is unknown or cannot be used with the specified Author.When placing a lab order via the RequestGroup, the tenant location or ID is incorrect or does not match to the Author (the provider).
429Too many requestsThis error represents the user being throttled. The specific throttle will be described in the respond payload. This throttle could be the RPS or the number of concurrent p360 async processes.
454No error messageThis is usually caused by trying to call a temporary link that has expired.
504Gateway TimeoutThis usually occurs when a synchronous call takes longer the 60 seconds to complete.