Error messages

When a Client calls an endpoint on the HelseID server, and the HelseID server for some reason will not validate the request, an error may occur.

Generic error messages

The following (generic) error messages are defined in the OAuth 2.0 and OpenID Connect protocols. For each kind of error message, there may be multiple causes for the error message to occur. Below is a list of most of the error messages you can encounter.

Error code Interpretation of the error
invalid_request The request against the Token endpoint was invalid. Some possible causes are: An invalid HTTP Method or Content Type was used (HelseID expect POST and "application/x-www-form-urlencoded"), or an invalid Authorization Code was used.
invalid_client The Client was not authenticated properly. This error can occur when the private_key_jwt element has been signed with an invalid key. It can also occur if an invalid Client ID was used in the request.
invalid_grant This error typically occurs when an invalid Refresh Token, or Authorization Code is used, if the refresh token or Authorization Code has expired, and/or in cases where the supplied parameters are invalid. When using PKCE, make sure that it is used correctly. Also make sure that the supplied redirect URI is valid.
unauthorized_client This error usually indicates that the Client is trying to use a grant type that it is not allowed to use, or that a redirect URI is required, but none was specified.
unsupported_grant_type Indicates that the grant type parameter is missing, or invalid for the specified Client.
unsupported_response_type This error should only occur if the response type parameter is missing.
invalid_scope The Client is either requesting scopes it is not allowed to access, or it is requesting identity scopes when running in a machine-to-machine (Client Credentials) flow.
use_dpop_nonce The Client has requested a DPoP Token, but the DPoP proof provided in the call to the Token endpoint does not contain a nonce. HelseID will indicate this as an error, however, the error is only used as a technical mechanism to provide the Client with a DPoP nonce.

The following error codes are only relevant for Clients that sends information in JSON structures to HelseID. Examples of this include parent or child organization numbers, nhn:tillitsrammeverk:parameters, or other types of contextual claims. In these cases, the error description will contain a prefix that describes the context of the error and a text describing what went wrong.

Error code Description prefix Comment
unauthorized_client HID-AUTH: The client is not authorized for the supplied JSON structure. This implies that the Client cannot send in the type of JSON specific to the request.
invalid_request HID-JSON: The JSON type could not be parsed. This implies that the Client has not sent in a valid JSON document.
invalid_grant HID-GRANT: The client is not using the correct grant type. This implies that the Client has used the wrong grant type for the type of JSON that is has sent in.
invalid_request HID-TYPE: The JSON type could not be validated. This implies that the JSON type (i.e. the scope for the JSON structure) is not recognized.
invalid_request HID-STRUCTURE: The JSON structure could not be validated. This implies that JSON structure from the Client is not structured according to the relevant model.
invalid_request HID-CONTENT: The JSON content could not be validated. This implies that the JSON structure from the Client contains invalid data.
access_denied HID-DOUBLE-STRUCTURE: The request contained a Tillitsrammeverk structure; however, the structure has already been sent in in another flow. This implies that the Client has used both the PAR (or Authorization) endpoint as well as the Token endpoint for the use of nhn:tillitsrammverk:parameters.

Example of a complete error description:

HID-CONTENT: The JSON content could not be validated.
At node '$.practitioner_role.organization.identifier.value': No delegation could be found from the organization with org no '100100579' to the supplier, i.e. the provider of the client with client_id = 'ed7c8de2-5ceb-4c02-adb9-3946140eea16'. The client is therefore not allowed to use this organization's number.