> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waec.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Codes and Responses

> Understand WAEC API error responses: HTTP status codes, application-level error codes, rate limit handling, and best practices for robust error handling.

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:

```json theme={null}
{
    "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 |

<Tip>
  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.
</Tip>