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. |
Error messages related to the use of JSON structures from the Client:
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.