Error Scenarios, Solutions and Frequently Asked Questions

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.

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

The HTTP 429 (Too Many Requests) error is returned when there are too many concurrent requests to the interface or when the number of requests exceeds the processing capacity of the interface.

Call throttling and load management
 
The Vero API interfaces apply throttling and rate limiting to ensure the stability and balanced use of the service. This means that the service controls both the request arrival rate and the number of concurrent requests, and dynamically limits them according to the capacity available. The limitations are typically based on the following principles:

• Rate limit: how many requests are allowed in a given period of time (for example, requests/second or requests/minute).
• Burst limit: the limit can be exceeded briefly but only up to a specified maximum.
• Concurrency limit: the number of requests that can be processed at the same time.
• Dynamic load balancing: the allowed limits may change up or down depending on the total load of the service.

If any of the above limits is exceeded, the interface returns the response: HTTP 429 Too Many Requests
 
Operating model for interface users
 
Interface users should implement client-side load management in accordance with the following best-practice principles:

• Balancing of requests
  • Avoid sudden spikes (burst traffic)
  • Distribute calls steadily over time (rate smoothing)
• Retry and backoff strategy
  • In the case of HTTP 429, do not repeat the request immediately but retry with a delay:
    • Use exponential backoff
    • Add random jitter to avoid spikes

Example:
1. Attempt 1: immediately
2. Attempt 2: +1 s
3. Attempt 3: +2 s
4. Attempt 4: +4 s (+ random variation)

Limiting concurrency

• Limit the number of simultaneous threads / parallel calls
• Use connection-pool or worker limitations, for example

Idempotent calls

• Design calls for secure resending

Making use of hints

• If the response contains a hint about waiting time (for example, Retry-After), follow the hint.

Important to note

• No exact numerical limits have been published because they can change dynamically depending on the load.
• Limitations may be directed to different levels (for example, client, identifier, IP, application).
• The aim of the limitations is to eliminate individual operators’ effect on the availability of the entire service.

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