Troubleshooting Error SPECARIA-MTLS-0001: Client Certificate Rejection
Explains the SPECARIA-MTLS-0001 error, a 401 response from the platform indicating a missing or invalid product client certificate during license-related
Overview
The error code SPECARIA-MTLS-0001 indicates that the platform has rejected an API request due to a client-side certificate problem. This is a mutual TLS (mTLS) authentication failure, returned as an HTTP 401 Unauthorized response.
This error specifically occurs during API calls that require a build-embedded product certificate for authentication, such as license heartbeat and license request operations. The platform expects a valid client certificate to be presented during the TLS handshake, and this error is returned when that certificate is either missing or invalid.
The system identifies this specific error by inspecting the HTTP response for a 401 status code and the presence of the SPECARIA-MTLS-0001 string within the response body.
Error Details
| Property | Value |
|---|---|
| Error Code | SPECARIA-MTLS-0001 |
| HTTP Status Code | 401 Unauthorized |
| Message | platform rejected: client certificate missing/invalid |
Cause
The root cause of this error is a failure in mTLS authentication. The API call was made without the required product client certificate, or the certificate provided was invalid. The platform's security policy requires this certificate for certain sensitive operations, and its absence or invalidity leads to an immediate rejection of the request.
Impact and Resolution
This error indicates a fundamental problem with the client's build or deployment configuration, not a transient network issue or an invalid license key. The product certificate is embedded into the software at build time.
IMPORTANT
A SPECARIA-MTLS-0001 error is a permanent failure for the running build. Retrying the API request will not resolve the issue, as a retry cannot cause the missing certificate to appear.
To resolve this error, you must investigate and correct the build and deployment process to ensure the product client certificate is correctly included in the application artifact.
Response Body Format
The platform's detection logic for this error is designed to be flexible regarding the structure of the JSON response body. The system scans the raw response body for the presence of the string SPECARIA-MTLS-0001 rather than parsing a specific JSON path.
The platform has been observed to return this error code in at least two different JSON structures. An API consumer might receive a response body similar to one of the following examples.
Example 1:
{
"error": "SPECARIA-MTLS-0001",
"error_description": "Client certificate required"
}
Example 2:
{
"error": {
"code": "SPECARIA-MTLS-0001",
"message": "mTLS client certificate missing or invalid"
}
}
NOTE
The system only logs and surfaces the SPECARIA-MTLS-0001 code itself. The full response body is not persisted or otherwise exposed by the system's internal error handling.
See Also
- For more information on platform API contracts, refer to the Chat API guide and the Product Integration guide.