Error Codes

Download

Focus Mode

Font Size

Last updated: 2026-08-28 16:06:56

AI-Translated

This document describes the generic error codes that THDS may return for FHIR resource operations, search operations, and Bundle transaction/batch operations. The actual error information returned by the API may vary depending on the resource type, request parameters, business rules, and permission configurations, but it generally follows the conventions below.
General Error Code Description
Error Code
Term
Description
Common Trigger Scenarios
400
Bad Request
The request format is incorrect, or the request parameters are invalid.
Malformed request body JSON, invalid resource ID, malformed search parameters, incorrect patch path, malformed Bundle structure
401
Unauthorized
Not authenticated, and valid credentials are missing.
Authentication information not provided, authentication token invalid, authentication token expired
403
Forbidden
Authenticated but not authorized to access the target resource or perform the operation.
No permission to create, update, delete, search, or execute transactions
404
Not Found
The requested resource, resource type, or path does not exist.
Specified resource does not exist, target API path is incorrect, target resource in transaction entry does not exist
409
Conflict
The current resource state or matching result conflicts with the operation requirements.
Version conflict, non-unique match for conditional create, non-unique match for conditional update, entry conflict within transaction
410
Gone
The resource or the specified historical version is no longer accessible.
Resource logically deleted, historical version inaccessible
415
Unsupported Media Type
Unsupported request content type.
Not using application/fhir+json, not using application/json-patch+json
422
Unprocessable Entity
The request syntax is correct, but it fails business or rule validation.
Incomplete FHIR resource structure, business constraint not satisfied, search expression parsable but not executable
500
Internal Server Error
Internal server processing exception.
Service execution exception, transaction processing exception, unknown internal error
Description by Interface Type
Basic Resource Operations
This applies to resource-level interfaces such as Create, Read, vRead, Update, Delete, and Patch. Common scenarios are as follows:
400 Bad Request: The resource content submitted during creation or update does not meet the JSON/FHIR structural requirements; the resource ID is invalid during read or delete operations; or the op, path, or patch document format is incorrect during a Patch operation.
403 Forbidden: The current caller does not have permission to create, read, update, or delete the corresponding resource.
404 Not Found: The specified resource does not exist, or the requested resource type endpoint does not exist.
409 Conflict: A version conflict occurs during an update, the current resource state does not allow deletion during a delete operation, or the target path does not match the current resource state during a Patch operation.
410 Gone: The resource or historical version that was read is no longer accessible.
415 Unsupported Media Type: The correct Content-Type (application/fhir+json) is not used for Create or Update operations, or the correct Content-Type (application/json-patch+json) is not used for a Patch operation.
422 Unprocessable Entity: The resource content is syntactically correct but fails validation against business rules or FHIR rules.
Search Operations
This applies to APIs such as basic search, reference search, numeric search, date-time search, pagination, sorting, full-text search, and full patient information search. Common scenarios are as follows:
400 Bad Request: The search parameter format is incorrect, or the parameter value is invalid, for example, due to an incorrect date comparison prefix, a malformed numeric expression, an invalid sort field, or incorrect pagination parameters.
403 Forbidden: The current caller does not have permission to search for the corresponding resource or access full patient information.
404 Not Found: The specified resource type does not exist, or the target patient does not exist.
422 Unprocessable Entity: The search syntax is correct but fails validation against business rules, permission rules, or resource-level constraints.
Bundle Transactions and Batch Operations
This applies to APIs such as basic Bundle transactions, bundling multiple associated resources, placeholder IDs and references, conditional creation, conditional update, deletion within a transaction, and Patch operations within a transaction. Common scenarios are as follows:
400 Bad Request: This indicates errors such as an invalid Bundle structure, malformed entry requests, illegal placeholder IDs, invalid reference paths, or incorrectly formatted conditional expressions.
404 Not Found: The target resource path in the Bundle entry cannot be found, or the target resource for the transactional operation cannot be found.
409 Conflict: This indicates conflicts such as a duplicate resource ID, conflicting reference relationships, non-unique matches for conditional create/update operations, or a transaction rollback due to a failed deletion entry.
422 Unprocessable Entity: The Bundle syntax is correct, but validation of the resource content, reference relationships, or business rules has failed.
Usage Recommendations
Before calling a write-type API, ensure that the Content-Type and the request body structure meet the requirements.
Before performing update, delete, Patch, or transactional operations, confirm that the target resource exists and the current caller has the required permissions.
When using APIs for search, conditional create, or conditional update, ensure that the search criteria are as specific and unique as possible.
When handling errors such as 409 and 422, it is recommended to further pinpoint field-level or business-level issues by examining the specific response content.

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

tencent cloud

Tencent Healthcare Data Services

Error Codes

General Error Code Description

Description by Interface Type

Basic Resource Operations

Search Operations

Bundle Transactions and Batch Operations

Usage Recommendations

Help and Support

Error Code	Term	Description	Common Trigger Scenarios
400	Bad Request	The request format is incorrect, or the request parameters are invalid.	Malformed request body JSON, invalid resource ID, malformed search parameters, incorrect patch path, malformed Bundle structure
401	Unauthorized	Not authenticated, and valid credentials are missing.	Authentication information not provided, authentication token invalid, authentication token expired
403	Forbidden	Authenticated but not authorized to access the target resource or perform the operation.	No permission to create, update, delete, search, or execute transactions
404	Not Found	The requested resource, resource type, or path does not exist.	Specified resource does not exist, target API path is incorrect, target resource in transaction entry does not exist
409	Conflict	The current resource state or matching result conflicts with the operation requirements.	Version conflict, non-unique match for conditional create, non-unique match for conditional update, entry conflict within transaction
410	Gone	The resource or the specified historical version is no longer accessible.	Resource logically deleted, historical version inaccessible
415	Unsupported Media Type	Unsupported request content type.	Not using `application/fhir+json`, not using `application/json-patch+json`
422	Unprocessable Entity	The request syntax is correct, but it fails business or rule validation.	Incomplete FHIR resource structure, business constraint not satisfied, search expression parsable but not executable
500	Internal Server Error	Internal server processing exception.	Service execution exception, transaction processing exception, unknown internal error