How-To: Troubleshoot API Errors¶
Find the step of a signing or certificate workflow that failed, and why, from the HTTP status code the Keyserver returned. Status meanings and the error body are in the Error Codes Reference.
Read the reason in the error body before anything else: properties[].message, or detail when properties is empty. See Error response format.
Signing workflow¶
flowchart TD
A["Request an access token"] --> A1{"Token issued?"}
A1 -- "no" --> AX["No token"]
A1 -- "yes" --> B["POST /api/operations"]
B -- "error" --> BX["401 Not authenticated<br/>403 No createoperation<br/>400 Malformed request<br/>404 Unknown or revoked keyid<br/>409 Key not initialized or listed twice"]
B -- "201" --> C{"Operation approved?"}
C -- "no" --> C1["Approver approves<br/>on the Approvals page"]
C1 -- "error" --> CX["409 Approval refused<br/>410 Gone"]
C1 --> C
C -- "yes" --> D["POST /api/signorders"]
D -- "error" --> DX["409 Conflict<br/>404 Unknown operation or key<br/>403 No order permission<br/>410 Gone<br/>400 Malformed request"]
D -- "201" --> E{"Signature verifies?"}
E -- "no" --> EX["Wrong hash algorithm"]
E -- "yes" --> F["Signed"]Diagram: Request an access token; Token issued?; no; No token; yes; POST /api/operations; error; 401 Not authenticated 403 No createoperation 400 Malformed request 404 Unknown or revoked keyid 409 Key not initialized or listed twice; 201; Operation approved?; Approver approves on the Approvals page; 409 Approval refused 410 Gone; POST /api/signorders; 409 Conflict 404 Unknown operation or key 403 No order permission 410 Gone 400 Malformed request; Signature verifies?; Wrong hash algorithm; Signed
| Step | Result | Cause | Reference |
|---|---|---|---|
| Request an access token | No token | Wrong client credentials or authorization server URL. The Keyserver is not involved yet | Authentication Model |
POST /api/operations | 401 | Not authenticated | Diagnosing 401 vs 404 vs 403 |
403 | No createoperation on a key | Creating an operation | |
400 | Malformed request | Creating an operation | |
404 | Unknown or revoked keyid | Creating an operation | |
409 | Key not initialized, or listed twice | Creating an operation | |
| Approval | 409 | Approval refused | Status codes |
410 | Operation cancelled, or a key in it revoked | Status codes | |
POST /api/signorders | 409 | Not approved, usage exhausted, not the creator, not a FW key, or a key not initialized | Signing |
404 | Unknown operation or key, or key not in the operation | Signing | |
403 | No order on every key in the operation | Signing | |
410 | Operation expired or cancelled, or a key revoked | Signing | |
400 | Malformed request | Signing | |
| Verify the signature | 201, but the signature does not verify | Hash not made with the key's hash algorithm | Signing |
While the operation waits for approval, GET /api/operations/{id} returns approved: false. How approvers find and approve operations is in The approval workflow.
Certificate workflow¶
Authentication, operation creation and approval fail as in the signing workflow. The operation names a CA key.
flowchart TD
A["Operation approved<br/>see Signing workflow"] --> B["POST /api/certificates"]
B -- "error" --> BX["409 Conflict<br/>404 Unknown operation or key<br/>403 No createcertificate<br/>410 Gone<br/>400 Malformed request"]
B -- "200" --> C["Certificate issued"]Diagram: Operation approved see Signing workflow; POST /api/certificates; error; 409 Conflict 404 Unknown operation or key 403 No createcertificate 410 Gone 400 Malformed request; 200; Certificate issued
| Result | Cause | Reference |
|---|---|---|
409 | Not approved, usage exhausted, not the creator, not a CA key, or a key not initialized | Certificate issuance |
404 | Unknown operation or key, or key not in the operation | Certificate issuance |
403 | No createcertificate on every key in the operation | Certificate issuance |
410 | Operation expired or cancelled, or a key revoked | Certificate issuance |
400 | Malformed csrpem or serialnumber | Certificate issuance |
Diagnosing 401 vs 404 vs 403¶
The status tells you which layer rejected you: the token, the subject registration, or the permissions. 401 has two forms, told apart by the detail text.
401 (ordinary): the token itself is the problem. The Keyserver could not validate it. Check, in order:
- Is the token present in
Authorization: Bearer <token>? - Has the token expired? Tokens are short-lived; fetch a fresh one per pipeline run.
- Does the
audclaim match the Keyserver's configured audience? - Was it issued by the configured identity provider?
401 "The user/client is not valid": the token is valid, but no registered subject matches it. A new client with a mismatched ID gets this 401 on every call, which is easy to misread as a credentials problem. Check:
- Does a subject exist whose Subject ID matches the token's identity claim? Copy the claim's value as issued rather than retyping it. For clients, a Subject ID ending in
*matches any identity that starts with the text before the*, ignoring case; user logins do not use wildcards. On a user's first login, the username claim (such aspreferred_username) is matched against the Subject name instead. - Was the subject deleted? Deletion renames the subject, so the token no longer matches it. See Manage Subjects in the Keyserver.
Reading the claim without external tooling
In the Keyserver UI, the About page's "View ID Token" and "View Access Token" links decode the token's claims; compare sub/oid (users) or the client identity claim with the registered Subject ID. Client-credentials clients have no UI session, so decode their access token payload locally, for example with jq.
404: an unknown resource, not a subject problem. The subject was recognized, but the keyid, operation ID or datastore entry in the request does not exist, the key is not part of the operation, or the datastore entry was deleted. POST /api/operations also returns 404 for a revoked keyid. Check the identifier in the request against what exists.
403 "Access forbidden": the subject is recognized, and permissions are the problem. Check, in order:
- Does the subject have a role granting the API being called (for example
orderorcreateoperation)? - Is the permission scoped to the specific key in the request?
orderonfw-quickstartdoes not grantorderon a different key. - Is the subject registered but role-less? A subject with no key-scoped permissions gets
403fromGET /api/keysitself. - Was the token issued by the CI/CD authorization server? The pipeline endpoints (operations, sign orders, certificates, keys, datastore) refuse a token from the administrative identity provider with
403"Authorization error" ("Authentication by CI/CD authorization server is required for method ...").
A request against an operation that another client created with creatorowns: true (the default) is refused with 409; only the creator may use it.
Related pages¶
- PKCS#11 Library Reference: failures when signing through the PKCS#11 module, where the status code is not shown directly