diff --git a/src/doc/docs/faq.md b/src/doc/docs/faq.md index 056d34dc..4d753a8d 100644 --- a/src/doc/docs/faq.md +++ b/src/doc/docs/faq.md @@ -25,7 +25,7 @@ You can still revoke certificates without account key pair though, see [here](us **Cause:** There may be multiple causes for that, but usually it means that the CA could not verify your challenge. -**Solution:** If the status is `INVALID`, invoke `Challenge.getError()` to get the cause of the failure. For example, you can log the output of `challenge.getError().toString()`. Make sure that your challenge is ready for verification _before_ you invoke `Challenge.trigger()`. Also make sure not to remove the challenge until the status is either `VALID` or `INVALID`. +**Solution:** If the status is `INVALID`, invoke `Challenge.getError()` to get the cause of the failure. For example, you can log the output of `challenge.getError().toString()`. Make sure that your challenge is ready for verification _before_ you invoke `Challenge.trigger()`. Also make sure not to remove the challenge until the status is either `VALID` or `INVALID`. Read more about errors [here](usage/errors.md). ## My `Order` returns status `INVALID`. What has gone wrong? @@ -33,7 +33,7 @@ You can still revoke certificates without account key pair though, see [here](us **Cause:** There may be multiple reasons for that. It seems that you are still missing steps that are required by the CA before completion. -**Solution:** If the status is `INVALID`, invoke `Order.getError()` to get the cause of the failure. For example, you can log the output of `order.getError().toString()`. +**Solution:** If the status is `INVALID`, invoke `Order.getError()` to get the cause of the failure. For example, you can log the output of `order.getError().toString()`. Also see [here](usage/errors.md). ## My `Order` seems to be stuck in status `PROCESSING`. What can I do? @@ -88,5 +88,5 @@ Unfortunately, manual action is required in any case, there is no way to automat ## Where can I find more help? * [Let's Encrypt Documentation](https://letsencrypt.org/docs/) -* [Let's Encrypt Community](https://community.letsencrypt.org/) - If the question is _acme4j_ related, please mention it in your post. +* [Let's Encrypt Community](https://community.letsencrypt.org/) - If the question is _acme4j_ related, please mention it in your post. I don't read the forum every day, but I will answer as soon as I notice it. * [SSL.com Knowledgebase](https://www.ssl.com/info/) diff --git a/src/doc/docs/usage/errors.md b/src/doc/docs/usage/errors.md new file mode 100644 index 00000000..1a13f322 --- /dev/null +++ b/src/doc/docs/usage/errors.md @@ -0,0 +1,15 @@ +# Errors + +The CA will send all errors as [RFC7807](https://datatracker.ietf.org/doc/html/rfc7807) problem documents. _acme4j_ parses these documents and provides a `Problem` representation of them. + +The simplest way to handle the problem is to log the result of its `.toString()` method. It contains a summary of all important fields. + +There are other methods that return machine- and human-readable details and subproblems. With `.asJSON()` you can also get a JSON representation of the full problem document, in case there are non-standard fields. + +## Errors while Ordering + +If your challenge has failed, you can retrieve the cause of the failure with `Challenge.getError()` or `Order.getError()`. It returns an `Optional` containing further details why the challenge has failed. + +## Exceptions + +`AcmeServerException` and its subclasses provide a `getProblem()` method that returns the `Problem` that caused the exception. The exception message also contains a summary of the problem. diff --git a/src/doc/mkdocs.yml b/src/doc/mkdocs.yml index 20d5c42b..6d2dc0e6 100644 --- a/src/doc/mkdocs.yml +++ b/src/doc/mkdocs.yml @@ -30,6 +30,7 @@ nav: - 'usage/renewal.md' - 'usage/revocation.md' - 'usage/persistence.md' + - 'usage/errors.md' - 'usage/exceptions.md' - 'usage/advanced.md' - 'usage/debugging.md'