Api

Error Reference

ACME and REST API error responses from uPKI RA.

ACME error format (RFC 7807)

All ACME errors follow RFC 7807 Problem Details:

{
  "type": "urn:ietf:params:acme:error:<code>",
  "detail": "<human-readable message>",
  "status": <http_status_code>
}

Type	HTTP status	Cause
`malformed`	400	Request body is malformed or missing required fields
`unauthorized`	403	JWS signature invalid or account not authorized
`rateLimited`	429	Too many requests
`orderNotReady`	403	Trying to finalize an order that is not in `ready` state
`badCSR`	400	CSR fields do not match the order identifiers
`badNonce`	400	Nonce not found or already used
`serverInternal`	500	Internal RA or CA error

Non-ACME endpoints return:

{
  "status": "error",
  "message": "<detail>"
}

Traefik's LEGO client cannot validate the RA's TLS certificate.

Resolution: Inject ca.crt from the RA data volume into Traefik's trust store before startup. See Traefik Integration.

The start command needs the seed for first-boot registration.

Resolution: Set UPKI_CA_SEED in your environment or Docker Compose file.

listen was called but no ra.crt / ra.key exist.

Resolution: Run register first, or use start for auto-bootstrap.

The client is reusing nonces.

Resolution: Fetch a fresh nonce from GET /acme/new-nonce before every signed request.

The order's authorizations are not all in valid state.

Resolution: Complete and validate all challenges before calling finalize.

The identifiers in the CSR do not match the order identifiers.

Resolution: Ensure the CSR's Common Name and/or SANs match exactly the identifiers submitted in the original new-order request.

# Show detailed RA logs
docker logs upki-ra --follow

# Enable debug mode (bare-metal)
python ra_server.py listen --debug

The RA logs every ACME request, ZMQ call to the CA, and the CA's response.

ACME Endpoints

Complete list of ACME v2 (RFC 8555) endpoints exposed by uPKI RA.

Contributing

How to contribute to uPKI RA.