All errors returned by the Digital Certificate Confirmation API follow a consistent JSON structure that includes the HTTP status code, a machine-readable subCode string, and a human-readable message description.
Error Response Structure
Every error response has the following shape:
{
"status": "FAILED",
"message": "Invalid key provided.",
"data": null,
"subCode": null
}
status — always "FAILED" for error responses.subCode — a stable, uppercase string identifier for the error condition. Use this field in your error handling logic.message — a human-readable explanation suitable for logging or displaying to developers.
HTTP Status Codes
| Code | Meaning |
|---|
200 | Success — the request completed successfully |
401 | Unauthorized — the X-DigiCert-Secret header is missing or invalid |
404 | Not Found — the requested resource does not exist |
422 | Unprocessable Entity — the request body is well-formed but failed validation rules |
500 | Internal Server Error — an unexpected error occurred on the server |
Application Error Codes
| Code | HTTP Status | Description |
|---|
UNAUTHORIZED | 401 | The X-DigiCert-Secret key is missing or invalid |
VALIDATION_ERROR | 422 | One or more request fields are missing or contain invalid values |
Always check the subCode field in your error handling logic rather than branching only on the HTTP status code. Using subCode lets you respond to each failure condition precisely.
