API Error Codes and Responses - WAEC Certificate Digitization

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.