> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auditrails.io/llms.txt
> Use this file to discover all available pages before exploring further.
# AuditRails Error Codes: Complete API Error Reference
> Complete reference for every AuditRails API error code — its HTTP status, root cause, and the exact resolution steps to fix your integration.
When an AuditRails API request cannot be completed, the response body always contains a structured error object. Every error carries a stable machine-readable `code`, a human-readable `message`, and a `request_id` you can share with support. Familiarizing yourself with the error taxonomy makes it straightforward to write robust error-handling logic in your integration.
## Error Response Structure
All errors — regardless of category — follow the same JSON envelope:
```json theme={null}
{
"error": {
"code": "auth/key_not_found",
"message": "API key not found. Verify the key is correct or generate a new one from the dashboard.",
"request_id": "req_01HX...",
"doc_url": "https://docs.auditrails.io/reference/error-codes"
}
}
```
A slash-namespaced, stable identifier for the error (e.g. `auth/key_not_found`). Use this field in your error-handling switch statements — `message` text may change without notice.
A plain-English description of the problem and, where relevant, how to fix it. Suitable for logging but not for display to end users.
A unique identifier for the specific API request that failed. Always include this when contacting support.
Always points to this page. Useful when surfacing errors in dashboards or alerting systems.
Errors in the `action/*` namespace may include two additional fields: `suggestion` (a recommended fix) and `valid_actions_url` (a direct link to your project's action catalog). Check for these fields when handling action validation errors.
***
## Authentication Errors — `401 Unauthorized`
These errors occur before any request processing. Check your API key configuration first.
| Code | Description | Resolution |
| --------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `auth/missing_header` | The `Authorization` header is absent from the request. | Add `Authorization: Bearer at_live_...` to every request. |
| `auth/invalid_format` | The `Authorization` header is present but malformed. | The header must be exactly `Bearer ` — no extra whitespace or encoding. |
| `auth/key_not_found` | The API key does not exist in AuditRails. | Verify the key was copied in full, or generate a new one from **Dashboard → API Keys**. |
| `auth/key_revoked` | The API key has been explicitly revoked. | Generate a replacement key from **Dashboard → API Keys**. |
| `auth/key_expired` | The API key has passed its expiry date. | Generate a replacement key from **Dashboard → API Keys**. |
Never log your full API key in error reports or support tickets. When contacting support, share only the first 10 characters of the key prefix (e.g. `at_live_abc`). This is enough for the support team to identify the key without compromising your account.
***
## Subscription Errors — `402 Payment Required`
| Code | Description | Resolution |
| ---------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `subscription/trial_expired` | Your free trial period has ended and no payment method is on file. | Add a payment method from **Dashboard → Billing**. Your event data is retained and immediately accessible once billing is activated. |
***
## Rate Limiting Errors — `429 Too Many Requests`
All `429` responses include a `Retry-After` header indicating the number of seconds to wait before retrying. See the [Rate Limits reference](/reference/rate-limits) for full details on limits by plan and key type.
| Code | Description | Resolution |
| -------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `rate/limit_exceeded` | Your project has exceeded its per-plan request rate for the current second. | Wait the number of seconds specified in `Retry-After`, then retry. Consider upgrading your plan for a higher limit. |
| `rate/ip_limit_exceeded` | The originating IP address has exceeded the global 100 req/s per-IP limit. | Spread traffic across multiple IPs or reduce request frequency. |
| `rate/test_limit_exceeded` | A test key (`at_test_...`) has exceeded its 60 req/s limit. | Switch to a live key (`at_live_...`) for production workloads. |
All AuditRails SDKs automatically retry rate limit errors with exponential backoff — you do not need to implement this yourself when using the `log()` batch method. Only `logDirect()` surfaces rate limit errors as exceptions.
***
## Validation Errors
These errors indicate a problem with the structure or content of your request payload. They must be fixed in your code before retrying — retrying without changes will produce the same error.
| Code | HTTP Status | Description | Resolution |
| ---------------------------- | ----------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `validation/missing_action` | `422` | The required `action` field is absent from the event payload. | Include the `action` field in every event. See [Event Schema](/reference/event-schema). |
| `validation/invalid_json` | `400` | The request body is not valid JSON. | Check for trailing commas, unescaped characters, or encoding issues in your payload. |
| `validation/batch_too_large` | `400` | The batch contains more than 100 events. | Split your batch into multiple requests of up to 100 events each. |
| `validation/batch_empty` | `400` | The batch array is present but contains zero events. | Include at least one event object in the `events` array. |
| `validation/body_too_large` | `413` | The request body exceeds the size limit. | Keep single-event requests under **256 KB** and batch requests under **2 MB**. Move large data to external storage and log a reference. |
***
## Event Errors
| Code | HTTP Status | Description | Resolution |
| --------------------------------- | ----------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `event/write_failed` | `500` | AuditRails encountered an internal error while persisting the event. | Retry the request. All SDKs handle this automatically with exponential backoff. |
| `event/idempotency_key_conflict` | `409` | An idempotency key was reused with a different payload. | Use a new idempotency key, or replay the exact original request body to retrieve the cached response. |
| `event/idempotency_key_in_flight` | `409` | A request with this idempotency key is currently being processed. | Wait a moment and retry — the in-flight request will resolve shortly. |
***
## Read Errors
| Code | HTTP Status | Description | Resolution |
| --------------------- | ----------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `read/invalid_params` | `400` | One or more query parameters are unrecognized or incorrectly formatted. | Check the [API Reference](/api-reference/get-events) for valid parameter names and formats. |
| `read/query_failed` | `500` | AuditRails encountered an internal error while executing the query. | Retry the request. Contact support if the error persists. |
| `read/not_found` | `404` | No event was found for the given `log_id`. | Verify the `log_id` is correct and that you are querying within the right project scope. |
***
## Action & Framework Errors
These errors relate to the action catalog and compliance framework configuration for your project.
| Code | HTTP Status | Description | Resolution |
| -------------------------------- | ----------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `action/invalid` | `422` | The `action` value is not in the compliance catalog and is not registered as a custom action. | Check your spelling. Retrieve the full list of valid actions with `GET /v1/actions`. |
| `action/requires_framework` | `403` | The action belongs to a compliance framework not enabled for your project. | Enable the required framework from **Dashboard → Billing → Frameworks**. |
| `action/missing_required_fields` | `422` | The action requires additional metadata fields that were not provided. | Call `GET /v1/actions` and check the `required_fields` array for this action. |
| `framework/disabled` | `403` | A previously enabled compliance framework has been disabled on your account. | Contact [AuditRails support](https://auditrails.io/contact) to re-enable or migrate the framework. |
***
## Server Errors — `500 Internal Server Error`
| Code | Description | Resolution |
| ----------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `server/internal` | An unexpected internal error occurred that does not fall into a more specific category. | Retry the request. If the error persists for more than a few minutes, contact support with your `request_id`. |
All AuditRails SDKs automatically retry `5xx` errors using exponential backoff. You only need to handle these manually if you are integrating directly with the HTTP API.
***
## Contacting Support
If you need to escalate an error to the AuditRails support team, include the following in your report:
1. The **`request_id`** from the error response (e.g. `req_01HX...`)
2. The **timestamp** of the failed request
3. The **first 10 characters** of your API key prefix (e.g. `at_live_abc`) — never the full key
4. The full **error code** (e.g. `server/internal`)
Reach the support team at [auditrails.io/contact](https://auditrails.io/contact).