Common Error Scenarios and Solutions

Make sure that you have completed the API portal acceptance testing:

• Production use of the APIs requires software acceptance testing. This testing is performed as a self-service in the API portal. The tester must have a production certificate.

If the acceptance testing has not been completed, the APIs will return the following error:

• "HTTP 403 Forbidden. Production access not granted. All test scenarios must be passed first."

Check the status of the software registered in the API portal, the selected APIs, and the API key used in the requests:

• "HTTP 401 Unauthorized. Software key header is missing." This error occurs if the SoftwareKey header is missing from the request or the header is in place but does not contain a valid API key.
• "HTTP 401 Unauthorized. Software key is not associated to an application in the API portal." This error occurs if the API key is inactive, does not belong to the specified software, or the software is not active in the API portal.
• "HTTP 401 Unauthorized. Software key is not integrated into the called service." This error occurs if the software and API key are active, but the specific API/service has not been selected for the software in the API portal.

Read more:  Software registration and acceptance procedure - vero.fi

Make sure that the following headers are included in every API request. If any of the following headers are missing, the request will fail and API access will be blocked.
Depending on the missing header, the following error messages may be returned:

• "HTTP 400 Bad Request. Missing HTTP Header: Accept".
• "HTTP 403 Forbidden Microsoft-Azure-Application-Gateway/v2".
• "HTTP 400 Bad Request. Missing HTTP Header: User-Agent".

Required headers:

• Accept: Indicates the expected response format. Typically set to application/json, meaning the client expects a JSON response.
• Content-Type: Specifies the format of the data being sent to the server. Usually application/json, indicating the payload is in JSON format.
• User-Agent: Identifies the application, operating system, device, and/or version making the request. This helps servers and network components understand the source of the request.

Note: Firewall rules for test APIs (apitest.vero.fi) were tightened on Monday, May 12, 2025, making these headers mandatory for all users.

In production (api.vero.fi), these headers are mandatory starting September 17, 2025.

Additional headers required by Vero APIs:

• Vero-SoftwareKey: Required for all APIs. This header must contain the software-specific API key.
• Vero-AuthorizationToken: Used when the API requires Suomi.fi authorization for acting on behalf of another customer.

Read more: Technical Guidelines for Vero API Interfaces - vero.fi

Certificate-related error messages:

• In certain certificate issues, the following error may be returned: "HTTP 403 Client certificate validation failed. Please check that the Vero API interface agreement is valid in the Certificate service".
• Check the listed situations in case of certificate-related errors.

API interface access not granted in the Certificate Service:

• Make sure that you have applied for Vero API access in the Certificate Service. Access must be requested separately for test and production certificates, depending on which environment you are calling.
• A common issue is using the same "Data Producer Web Service" certificate for the Incomes Register, Vero API, and APItamoPKI services, but only some of the interface accesses have been granted in the Certificate Service.
• If the Vero API access right is not granted, all API calls will fail.

Certificate has expired:

• Check the certificate validity in the Certificate Service.
• Request a new certificate in time or use the RenewCertificate PKI API to renew the existing one.
• Read more: Renewal of certificate - vero.fi

Use of test and production certificates:

• Make sure the correct type of certificate is used in your software's API calls.
• Vero APIs only support the "Data Producer Web Service" certificate type.
• Use a test certificate for test APIs.
• Use a production certificate for production APIs.
• Use a production certificate for API portal acceptance testing scenarios.
• The sandbox environment does not require a certificate.

Check whether the API requires Suomi.fi authorization.

• If the authorization is not valid, the following error is returned:
  "HTTP 1040 - No access to the requested data. Check that a valid authorization role exists in Suomi.fi authorization service."

Other authorization-related errors:

• The authorization token has expired. Tokens are valid for 60 minutes.
• The business IDs specified in the token are incorrect or have not granted authorization for the token user.

The requirement for Suomi.fi authorization is specified in each API’s documentation in the API portal. Not all APIs require Suomi.fi authorization.

• Read more: Acting on behalf of other organizations - vero.fi

Invalid input or connection issues:

• Make sure that your software complies with the schema, rules, and validations defined in the API documentation.
• If the API request contains invalid data, the following error is returned: "HTTP 400 Bad Request".

Avoid calling APIs during scheduled maintenance windows:

• During maintenance, the following error may be returned: "HTTP 500 Internal Server Error."
• Read more: Availability of Vero API service - vero.fi