AuditRails Error Codes: Complete API Error Reference

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:

{
  "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"
  }
}

string

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.

string

A plain-English description of the problem and, where relevant, how to fix it. Suitable for logging but not for display to end users.

string

A unique identifier for the specific API request that failed. Always include this when contacting support.

string

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 <api_key>` — 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 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.
`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 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 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:

The request_id from the error response (e.g. req_01HX...)
The timestamp of the failed request
The first 10 characters of your API key prefix (e.g. at_live_abc) — never the full key
The full error code (e.g. server/internal)

Reach the support team at auditrails.io/contact.

Getting Started

Guides

Reference

AuditRails Error Codes: Complete API Error Reference

Error Response Structure

Authentication Errors — `401 Unauthorized`

Subscription Errors — `402 Payment Required`

Rate Limiting Errors — `429 Too Many Requests`

Validation Errors

Event Errors

Read Errors

Action & Framework Errors

Server Errors — `500 Internal Server Error`

Contacting Support

​Error Response Structure

​Authentication Errors — 401 Unauthorized

​Subscription Errors — 402 Payment Required

​Rate Limiting Errors — 429 Too Many Requests

​Validation Errors

​Event Errors

​Read Errors

​Action & Framework Errors

​Server Errors — 500 Internal Server Error

​Contacting Support

Error Response Structure

Authentication Errors — `401 Unauthorized`

Subscription Errors — `402 Payment Required`

Rate Limiting Errors — `429 Too Many Requests`

Validation Errors

Event Errors

Read Errors

Action & Framework Errors

Server Errors — `500 Internal Server Error`

Contacting Support