Error Codes Reference¶
The Keyserver API returns errors as RFC 9457 problem-detail JSON. This page covers the status codes, the error body, and common causes per workflow.
Status codes¶
| Status | Meaning | Typical causes |
|---|---|---|
200 | Success (GET, PUT, DELETE, and POST /api/certificates) | — |
201 | Created (POST /api/operations, /api/signorders) | — |
400 | Malformed request | Missing required field, non-hex inputdata, description too short, value out of range. Detail "HV000028: Unexpected exception during isValid call" (title "Validation error") stands in for the real reason in two cases: any refused Revoke in the approvals view, whether for a missing permission, an unknown or already cancelled operation, or a revoked key; and a sign order on an operation stranded by lowering Required Approvers |
401 | Not authenticated | Missing, expired or invalid token; wrong audience or issuer; token signature not verifiable; or a valid, correctly signed token whose identity has no registered subject (detail: "The user/client is not valid") |
403 | Authenticated but not allowed | Role lacks the permission for this API, or the permission is not scoped to this key. Also returned by GET /api/keys when the subject has no key-scoped permissions at all |
404 | Not found | Unknown keyid, or a revoked keyid in POST /api/operations; unknown operation ID; key not part of the operation; datastore entry deleted |
409 | Conflict | Operation not approved yet ("Need more approvers"); the key's usage count for this operation is exhausted; the operation is already approved; an approver has already approved it; the approver has no key left to approve in the operation ("User has nothing in this operation (left) to approve"); creatorowns is set and the caller is not the operation creator; the key is not initialized ("Signing key is not initialized!", or "Not initialized" on POST /api/operations); a keyid listed twice in a new operation; the key is the wrong type for the request (FW for sign orders, CA for certificates) |
410 | Gone | Operation expired (validms elapsed); operation cancelled ("Operation is cancelled": an approver clicked Revoke, or the operation was deleted); or a key named in the request or in the operation has been revoked ("Signing key has been revoked"; POST /api/operations returns 404 instead). Create a new operation, or use another key |
Error response format¶
All errors share one structure. A validation failure names the offending field in properties:
{
"type": "about:blank",
"status": 404,
"title": "Validation Error",
"detail": null,
"instance": "/api/keys/nosuchkey",
"properties": [
{
"key": "getkeys.keyid.nosuchkey",
"message": "Signing key is not found"
}
]
}
Other failures carry a single detail string and an empty properties:
{
"type": "about:blank",
"status": 400,
"title": "Invalid Request Property Format",
"detail": "Unexpected value 'pkcs1'",
"instance": "/api/signorders",
"properties": []
}
status/title: the HTTP status and error classinstance: the endpoint that rejected the requestproperties: an array of{key, message}objects.properties[].messageis the human-readable reason; read it first. The array is empty when the error is not field-specificdetail: the human-readable reason whenpropertiesis empty
All error responses are served as application/json; responses from the authentication and authorization checks add ;charset=UTF-8. Branch on the status code, not the media type.
The shape of properties differs in later product lines. On a newer Keyserver, confirm it against your own deployment before writing client code.
Diagnosing 401 vs 404 vs 403¶
The status tells you which layer rejected a request: the token, the subject registration, or the permissions. What to check for each is in Troubleshoot API Errors, along with a flowchart per workflow that maps each failing step to the tables below.
Common failures per workflow¶
Creating an operation (POST /api/operations)¶
| Symptom | Cause |
|---|---|
| 403 | Subject lacks createoperation for one of the keys in new-keyusagerestrictions |
| 400 | description too short, or malformed new-keyusagerestrictions |
| 404 | A keyid in the request does not exist or has been revoked; the response does not say which (properties[].message "Not Found") |
| 409 | A key in the request is not INITIALIZED ("Not initialized"), or the same keyid appears twice ("Keys in an Pipeline Operation must be unique") |
Signing (POST /api/signorders)¶
| Symptom | Cause |
|---|---|
| 409 | Operation not approved yet ("Need more approvers"); the key's usage count for this operation is exhausted; creatorowns is set and the caller is not the operation creator; or the key is not FW type; the requested key or a key in the operation is not initialized ("Signing key is not initialized!") |
| 404 | Unknown operation ID; the keyid does not exist ("Signing key is not found"); or the key is not part of the operation ("The key is not associated with the given operation") |
| 403 | The subject lacks order on a key in the operation (order is required on every key the operation names) |
| 410 | Operation expired or cancelled, or the requested key or any other key in the operation has been revoked |
| 400 | The operation was pending when the key's Required Approvers was lowered ("Validation error", detail HV000028; create a new operation); inputdata not valid hex; signatureformat: p1363 on an RSA key; CMS options missing with cms or present with another format (see Signature Formats); or a value outside an enum, such as inputpadding: pkcs1, which the spec shows as an example but the server rejects (none and digestinfo are the accepted values) |
201, but the signature does not verify | The submitted hash was not made with the key's hash algorithm. The Keyserver does not check the length: with an RSA key the signature does not verify, and with an ECDSA key it verifies only against the hash algorithm you used |
Certificate issuance (POST /api/certificates)¶
| Symptom | Cause |
|---|---|
| 409 | Operation not yet approved ("Need more approvers"); the key's usage count for this operation is exhausted; creatorowns is set and the caller is not the operation creator; or the key is not CA type (only CA keys may sign CSRs); the requested key or a key in the operation is not initialized ("Signing key is not initialized!") |
| 404 | Unknown operation ID; the keyid does not exist ("Signing key is not found"); or the key is not part of the operation ("The key is not associated with the given operation") |
| 403 | The subject lacks createcertificate on a key in the operation |
| 410 | Operation expired or cancelled, or the requested key or any other key in the operation has been revoked |
| 400 | csrpem malformed, or exceeds 4096 characters; serialnumber not hexadecimal |
Key info (GET /api/keys, GET /api/keys/{keyid})¶
| Symptom | Cause |
|---|---|
| 403 "Access Denied" | Subject is registered but has no key-scoped permissions; the endpoint refuses instead of returning an empty list |
| 409 "Signing key is not initialized!" | The key exists but its material has not been generated yet (status NEW/RETRY), or generation failed (REJECTED). Wait for INITIALIZED; see Key status lifecycle |
| 410 "Signing key has been revoked" | The key has been revoked (FAILED); create or use another key |
| 404 | The keyid is misspelled or does not exist |
Datastore fetch (GET /api/datas/{keyid})¶
| Symptom | Cause |
|---|---|
| 403 | Client's role lacks the DATAKEY permission for this entry |
| 404 | Entry does not exist or was deleted (deletion renames the keyid) |
Related pages¶
- Access Control: the checks every API call passes, in order
- Troubleshoot API Errors: finding the failing step from the status code
- PKCS#11 Library Reference: troubleshooting signing through PKCS#11
- Audit Coverage Reference: which actions are recorded, and which are not