Troubleshooting
For detailed technical specifications, please refer to the Swagger documentation.
Error Responses From API Calls
| HTTP Code | When It Occurs | Short Description |
|---|---|---|
| 400 Bad Request | • Required query/header missing • JSON schema validation fails • Domain error in handling the request |
The request is syntactically or semantically invalid. |
| 401 Unauthorized | • No Authorization header supplied or the supplied HelseID DPoP token is missing, malformed, expired, or not signed correctly. |
The client is not authenticated. |
| 403 Forbidden | • Authenticated token does not grant permission for the HER‑Id(s) involved. |
Authenticated client lacks the required authorisation. |
| 404 Not Found | • Supplied message ID, configuration HER‑ID, or other resource does not exist (or has been purged). | The requested resource cannot be located. |
| 423 Locked | • Target HER‑ID is explicitly locked (clientLocked=true) by another authorised client.• Attempting to delete or update a locked configuration. |
The requested HER‑ID is currently reserved for exclusive use. |
| 500 Internal Server Error | • Unexpected server‑side failure, unhandled exception, downstream outage. | Generic server error – contact NHN support if it persists. |
Error response object
The type mshApiProblemDetails extends ProblemDetails and is based on RFC9110.
{
"title": "string", // short, human‑readable summary
"status": 400 | 401 | ..., // HTTP status code
"detail": "string | null", // longer description (may include HER‑IDs)
"instance": "string | null", // request path that caused the error
"errorCode": 1001 | 1202 | ..., // internal NHN error classification
"requestId": "string | null", // unique request identifier for tracing
"validationErrors": ["..."] | null, // only on 400 – list of field‑level errors
"stackTrace": "string | null", // not enabled in production
"timestamp": "2025-08-18T00:33:00"
}
Internal NHN Error Codes That May Be Returned
Currently implemented values in the "errorCode" property of the response object. The list may expand.
1000
API model validation error: The API request was rejected by the API controller middleware. Can be produced by http error response code 400.
1001
API request validation error: The API request was rejected by domain layer validation. The request was invalid, even though it fulfilled the model binding scheme. Can be produced by http error response code 400.
1010
The API request tried to access a message or other resource that was not found in the database. Can be produced by http error response code 404.
1020
The API request initiated an exchange with a EDI recipient whose EDI address belongs to a disallowed domain. For example test-edi → (prod-)edi or edi → gmail. Refer to the page for EDI limitations for detailed information. Can be produced by http error response code 400.
1100
The API request tried to create an application receipt on a business document which is already an application receipt. Can be produced by http error response code 400.
1102
The API request tried to create an application receipt on a business document, on behalf of a communication party HER-Id that was not a receiver of that business document. Can be produced by http error response code 400.
1200
The API request tried to access a business document, but the addressees of the message could not be deduced. Thus, we could not determine if the API request was authorized to access the business document. Can be produced by http error response code 403 in API V2, and by http error response code 400 in API V3.
1201
The API request tried to access a business document, but was not authorized for any of the addressees. The claim in the API request does not represent the sender, main receiver or any copy receiver of the message. Can be produced by http error response code 403.
1202
The API request tried to act on behalf of a communication party HER-Id it is not authorized for. The HER-Id in the request itself was not compatible with the provided authorization. Can be produced by http error response code 403.
1210
The API request tried to act on behalf of a communication party HER-Id that has been locked by another HelseID client. Can be produced by http error response code 423.
0
The error has no particular code, or was unhandled. Can be produced by all http error response codes.