REST API Error Codes
Error Codes
Whenever there is an error processing your API request, the API will return a straightforward JSON error message
carrying a success response object set to false, an error code as well as a text-based
error type.
You will find an example error as well as a list of all possible error codes and messages below.
Example Error:
{
"success": false,
"error": {
"code": 2803,
"type": "certificate_not_found"
}
}
Errors — General:
| Error Code / Type | Description |
|---|---|
101 / invalid_access_key |
User has provided an invalid API access key. |
102 / inactive_user |
You can not authenticate because your account is not active. |
103 / invalid_api_function |
User has provided an invalid API function. |
104 / route_not_found |
This route does not exist. Check the spelling in your request URL and also the HTTP method you are using (some endpoints can only be called using a POST request for instance). |
110 / invalid_request_body |
The body of your request was wrong. Please check your request arguments. |
111 / internal_server_error |
Something went wrong. If the problem persists, please contact our support team ([email protected]). |
112 / conflict |
The target resource can not be modified. |
113 / unprocessable_entity |
The syntax of your request was correct, but your request can not be processed. |
114 / conflict |
The target resource can not be modified. |
115 / invalid_json_request |
You have sent a JSON request, but it can not be decoded as JSON. Please check your input. |
116 / invalid_json_request_param |
You have sent an illegal parameter in your JSON request. Multidimensional arrays, objects and resources are not allowed. |
2800 / incorrect_request_type |
User has made a non-supported API request. |
2801 / permission_denied |
User does not have the permissions to access this resource. |
2802 / missing_certificate_hash |
User has not provided a certificate ID (hash). |
2803 / certificate_not_found |
The given certificate ID (hash) could not be found. |
Errors — Create Certificate:
| Error Code / Type | Description |
|---|---|
2804 / cannot_issue_certificate_unpaid_upgrade_invoices |
The current certificate cannot be issued due to unpaid invoices on a user account. |
2805 / invalid_certificate_type |
User has provided an invalid certificate type. |
2806 / missing_certificate_type |
User has not provided a valid certificate type. |
2807 / invalid_certificate_validity |
User has not provided a valid certificate validity. |
2808 / invalid_certificate_domain |
User has not provided one or more invalid certificate domains. |
2809 / wildcard_domains_not_allowed_in_multidomain_certificate |
Wildcards cannot be included in multi-domain certificates. |
2810 / invalid_domains_in_multidomain_request |
User has not provided one or more invalid domains in multi-domain request. |
2811 / duplicate_domains_in_array |
User has not provided one or more duplicate domains. |
2812 / missing_certificate_domains |
User has not provided any certificate domains. |
2813 / cannot_replace_certificate_other_replacement_in_draft |
Only issued certificates can be renewed or replaced by a new certificate. |
2814 / permission_denied_on_original_certificate |
User does not have the permissions to access certificate to renew. |
2815 / original_certificate_not_active |
Only issued certificates can be renewed or replaced by a new certificate. |
2816 / cannot_find_original_certificate |
Certificate to renew was not found. |
2817 / certificate_limit_reached |
Limit of certificates on user account was reached. |
2818 / invalid_certificate_csr |
User has not provided a valid CSR value. |
28181 / invalid_certificate_csr_for_non_wildcard |
You provided a CSR where the common name is a wildcard, but your certificate is not a wildcard. This will not work. It is recommended to leave the CSR common name completely empty, it is deprecated anyway. |
28182 / invalid_certificate_csr_for_wildcard |
You provided a CSR where the common name is not a wildcard, but your certificate is a wildcard. This will not work. It is recommended to leave the CSR common name completely empty, it is deprecated anyway. |
2819 / missing_certificate_csr |
User has not provided a CSR value. |
2820 / internal_error_failed_processing_csr |
Internal error processing CSR. Please contact support if this error occurs. |
2821 / internal_error_failed_creating_certificate |
Internal error generating certificate. Please contact support if this error occurs. |
2836 / csr_cn_is_invalid |
The CN (common name) in the CSR has an invalid value. Most probably it is not a valid internet address
(domain or IP without protocol). Valid examples: example.com, 127.0.0.1.Please note that the CSRs' CN (common name) should be exactly the first of your certificate_domains parameter. It is recommended to use a fresh, unique and correct CSR for
all certificates.
|
2839 / duplicate_certificates_found |
Domain can no longer be protected using Free Plan, upgrade to Basic Plan required. |
2841 / certificate_creation_locked_unpaid_invoices |
Your account has been temporarily suspended due to unpaid invoices. Please pay your open invoices in order to unlock this endpoint. |
2844 / missing_country_code |
Your CSR is missing the required Country (C) field. Please regenerate your CSR and include
a valid ISO 3166-1 alpha-2 country code (e.g. C=US, C=DE,
C=GB).
|
2880 / invalid_san |
Your SAN is being rejected. Most probably you have too many subject alternative names for your certificate or they have too many characters overall. |
Errors — Verify Domains:
| Error Code / Type | Description |
|---|---|
2822 / failed_showing_certificate |
The requested certificate could not be retrieved. |
2823 / failed_validating_certificate |
Domain verification failed and must be retried. Possible reasons for this are:
|
2824 / missing_validation_emails |
User has not provided a validation email for each domain in certificate. |
2825 / missing_validation_email |
User has not provided a validation email for each domain in certificate. |
2826 / internal_error_while_valdating_domain_control |
Internal error verifying domains. Please contact support if this error occurs. |
2827 / invalid_validation_method |
User has provided an invalid domain verification method. |
2828 / missing_validation_method |
User has not provided a domain verification method. |
2829 / incorrect_certificate_validation_type |
User has provided an invalid domain verification method or value. |
2830 / certificate_not_eligible |
The given certificate is not eligible for domain verification. |
2831 / certificate_not_ready_to_validate |
The given certificate is not ready for domain verification. |
2840 / invalid_caa_records_detected |
Invalid CAA records detected for some domains. Array of affected domains can be found in
details object. Learn more about CAA records.
|
2841 / caa_record_check_failed |
An internal error occurred checking your CAA records. If the problem persists please contact our support team ([email protected]). |
2842 / replacement_needs_same_common_name |
A replacement certificate needs the same common name as its replacement. |
2843 / ipv6_is_not_yet_supported |
We are working on providing IPv6 certificates. The feature is not yet available. |
2874 / certificate_restricted_top_level_domain |
We are not able to issue certificates for this Top-Level-Domain at the moment. Learn more. |
2875 / certificate_premium_not_allowed |
You are not allowed to issue premium certificates, most probably due to unpaid invoices or upgrades/downgrades. In case you think this is a mistake, please contact the ZeroSSL support team. |
2877 / certificate_unsupported_top_level_domain |
Certain TLDs are reserved for special purposes and we are not allowed to issue certificates for those.
Includes .local, .localhost, .example, .invalid,
.test, and others. You think there is a mistake on our side and issuing certs for this top
level domain should be allowed? Please contact our support team and describe the issue!
|
Errors — Download Certificate:
| Error Code / Type | Description |
|---|---|
2832 / certificate_not_issued |
The given certificate has not been issued yet. |
2860 / certificate_not_downloadable |
The certificate can currently not be downloaded. |
Errors — Revoke Certificate:
| Error Code / Type | Description |
|---|---|
2906 / revocation_failed |
The certificate can not be revoked currently, please try again later. If the problem persists — especially in urgent cases like key compromise — please contact our support team ([email protected]). |
2907 / certificate_not_in_revocable_state |
The certificate is not in a revocable state. Either the state has transitioned in the background, you are trying to revoke a certificate which can not be revoked due to its status or some process is going on in the background. If you think this is a mistake at our side please contact our support team ([email protected]). |
2908 / certificate_revocation_temporarily_blocked |
Due to customer protection mechanisms, your certificate can not be revoked at the moment. Try again some hours later. We temporarily disable revocation functionality, if high numbers of certificates are revoked. This was implemented as a preventive measure to limit possible loss in case of whatever related incident. Help and further information: ([email protected]). |
2909 / certificate_not_revocable_being_issued |
The certificate can not be revoked / cancelled because it is currently being issued. If this was a mistake, you may revoke it after issuance (most probably in 1-2 minutes). |
2910 / certificate_not_revocable_already_replaced |
The certificate has already been replaced by a new one. Does not apply for certificates where you have used the standard "renew" functionality of ZeroSSL, can only happen for special cases. |
Errors — Cancel Certificate:
| Error Code / Type | Description |
|---|---|
2833 / certificate_cannot_be_cancelled |
The given certificate cannot be cancelled due to its status. |
2834 / failed_cancelling_certificate |
Internal error cancelling certificate. Try again or contact support. |
Errors — Resend Verification:
| Error Code / Type | Description |
|---|---|
2837 / failed_resending_email |
Internal error resending verification email. Try again or contact support. |
Errors — Get Verification Status:
| Error Code / Type | Description |
|---|---|
2838 / failed_getting_validation_status |
Error retrieving domain verification status. Try again and make sure Email Verification is selected. |
Errors — Email verification:
| Error Code / Type | Description |
|---|---|
2950 / user_email_already_verified |
This email has already been verified. If this is your email, and you think this is a mistake, please contact our support team. |
2951 / user_email_verify_try_later |
There are too many email verification requests at the moment and a maximum limit has been hit. Please try again later. |
2952 / verification_email_missing |
The email you want to verify is missing in the request. |
2953 / verification_email_missmatch |
The verification emails do not match. |
2954 / verification_token_missing |
The verification token is missing in your email verification attempt. |
2955 / verification_token_invalid |
The email verification token is invalid. |
2956 / verification_token_expired |
The verification token is expired. Create a new token and finish the verification in time in order to resolve the issue. |
2957 / missing_email_in_email_change_request |
The email is missing in the email change request. |
2958 / invalid_email_in_email_change_request |
The email you have submitted in the email change request is invalid. |
2987 / email_already_exists |
That email is already registered in our system. An email must be unique in our system. If you think there is an issue, please contact our support team ([email protected]). |
2988 / new_email_matches_old_email |
Your new email seems to match your old email. If you want to verify your email you are calling the wrong endpoint. |
2993 / failed_to_send_verification_email |
Due to an internal error we have not been able to send the verification email. Please try again later or contact us if you need further assistance. |