Skip to content

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 class
  • instance: the endpoint that rejected the request
  • properties: an array of {key, message} objects. properties[].message is the human-readable reason; read it first. The array is empty when the error is not field-specific
  • detail: the human-readable reason when properties is 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)