Errors

The Invoance API uses standard HTTP status codes and a consistent JSON error structure across all endpoints. Errors are deterministic - the same invalid request always returns the same error code.

Error format

All error responses return a single JSON object with a machine-readable error code and a human-readable message. Never parse the message field programmatically, use the error field only.

4xx / 5xxStandard error

{
  "error":   "invalid_event_type",
  "message": "event_type is required and must be <= 128 chars."
}

Rate-limit and quota errors include additional fields to help you handle the condition programmatically:

429Rate-limit error

{
  "error":        "rate_limited",
  "message":      "Rate limit exceeded for your plan (builder: 50 req/sec).",
  "retry_after":  2,
  "plan_tier":    "builder",
  "limit_per_sec": 50,
  "upgrade_url":  "/dashboard/plans/upgrade"
}

429Quota error

{
  "error":         "quota_exceeded",
  "message":       "You've reached your monthly events limit (10000/10000).",
  "resource":      "events",
  "current_usage": 10000,
  "plan_limit":    10000,
  "plan_tier":     "builder",
  "upgrade_url":   "/dashboard/plans/upgrade"
}

HTTP status codes

200OK

Request succeeded.

201Created

Resource created successfully.

400Bad Request

Invalid request body or failed validation.

401Unauthorized

Missing or invalid authentication credentials.

403Forbidden

Insufficient scope, IP restriction, or feature not available on plan.

402Payment Required

Subscription is past due. Update your payment method to continue.

404Not Found

The requested resource does not exist.

409Conflict

Duplicate record, idempotency key reuse mismatch, or trace state conflict.

413Payload Too Large

Request body exceeds the maximum allowed size.

429Too Many Requests

Rate limit or quota exceeded. Back off and retry.

500Internal Server Error

Unexpected server error. Contact support if persistent.

Error codes

Use the error field to handle specific failure conditions in your integration. The status code provides the HTTP category; the error code provides the exact reason.

Authentication

missing_api_key401

No API key provided. Use the Authorization (Bearer) or X-API-Key header.

invalid_api_key401

API key does not exist or is invalid.

invalid_api_key_format401

API key must start with invoance_live_. Check that you are using the correct key.

invalid_authorization_scheme401

Authorization header must use the Bearer scheme.

api_key_revoked401

API key has been revoked and can no longer be used.

invalid_or_used_link401

Audit portal link is invalid, expired, or already exchanged. Portal links are single-use; mint a new one.

Authorization

insufficient_scope403

API key lacks the required scope (read, write, audit:read, or audit:write) for this operation.

ip_not_allowed403

Client IP address is not in the allowlist configured for this API key.

feature_not_available403

This feature is not included in your current plan. Upgrade to access it.

wrong_intent403

Audit portal link was minted for a different intent (audit_logs vs log_streams) and is not authorized for this action.

Validation, General

invalid_payload400

Request body is malformed JSON or fails schema validation.

bad_request400

Generic validation failure. Check the message field for details.

payload_too_large413

Request body exceeds the maximum allowed size for this resource.

Validation, Events

invalid_event_type400

event_type is required and must be 128 characters or fewer.

Validation, Documents

invalid_document_hash400

document_hash must be a 64-character lowercase hex SHA-256 string.

invalid_metadata400

metadata must be a valid JSON object.

metadata_too_large400

metadata exceeds the maximum allowed size.

invalid_original_bytes_base64400

original_bytes must be valid base64-encoded data.

original_bytes_empty400

original_bytes was provided but is empty.

original_bytes_too_large400

original_bytes exceeds the 5 MB limit.

original_bytes_hash_mismatch400

SHA-256 of the decoded original_bytes does not match document_hash.

Validation, AI Attestations

invalid_attestation_type400

attestation_type must be one of: output, decision, approval.

empty_payload400

input and output fields must not be empty.

invalid_context400

Model context fields (model, provider, etc.) must not be empty when provided.

subject_too_large400

Subject object exceeds the maximum allowed size.

subject_too_many_keys400

Subject object contains too many keys.

Validation, Traces

invalid_label400

Trace label is required and must be 255 characters or fewer.

metadata_too_large400

Trace metadata exceeds the 16 KB limit.

trace_empty400

Trace has no items. A trace must contain at least one event, document, or attestation to be sealed.

Validation, Audit Events

invalid_action400

action must be lowercase, dot-segmented (2 to 3 segments, e.g. user.signed_in or billing.invoice.paid), and 128 characters or fewer.

invalid_actor400

actor.type and actor.id are both required.

invalid_target400

Every entry in targets requires a type and an id.

too_many_targets400

targets may contain at most 20 entries.

invalid_occurred_at400

occurred_at must be a valid RFC3339 timestamp.

occurred_at_out_of_window400

occurred_at must fall within now minus 5 years and now plus 24 hours.

missing_idempotency_key400

The Idempotency-Key header is required on POST /audit/events. The SDKs generate one for you.

invalid_idempotency_key400

Idempotency-Key must be 255 characters or fewer.

Validation, Audit Orgs, Streams & Portal

invalid_organization_id400

organization_id is required and must be 255 characters or fewer.

invalid_name400

name must be 255 characters or fewer.

unsupported_stream_type400

Only webhook streams are supported right now.

too_many_streams400

This org has reached your plan's limit on stream destinations. Upgrade for more.

invalid_url400

Stream destination must be a valid absolute URL.

not_https400

Stream destination must use https://.

forbidden_destination400

Stream destination is not allowed (private, loopback, link-local, or metadata address).

invalid_format400

Export format must be csv or ndjson.

invalid_intent400

Portal intent must be audit_logs or log_streams.

invalid_duration400

Portal session_duration_seconds must be between 60 and 86400 (24h).

invalid_link_duration400

Portal link_duration_seconds must be between 60 and 3600 (1h).

Not Found

event_not_found404

No event exists with this ID.

document_not_found404

No document exists with this ID.

attestation_not_found404

No AI attestation exists with this ID.

trace_not_found404

No trace exists with this ID, or it does not belong to this tenant.

proof_not_found404

No proof record exists for this resource.

org_not_found404

Unknown audit org on ingest. Create it first via POST /audit/orgs; audit orgs are never auto-created.

not_found404

The requested audit resource (event, org, stream, or export) does not exist or is not visible to this key.

Conflict

duplicate_event409

An event with this idempotency key already exists. The existing record is returned.

idempotency_key_reuse_mismatch409

The idempotency key was previously used with a different request body.

document_already_anchored409

A document with this hash has already been anchored.

trace_sealed409

Trace is already sealed. No more items can be added.

trace_sealing409

Trace is currently being sealed. Retry after seal completes.

trace_not_open409

Trace is sealed or sealing. Items can only be added to open traces.

org_exists409

An audit org with this organization_id already exists. Reuse it; organization_id is the stable address for an org.

org_archived409

This audit org is archived and no longer accepts new activity (events, streams, portal links, exports). Unarchive it to resume.

org_not_deletable409

The org has signed history retention hasn't purged yet, or events accepted in the last 24 hours may still be in the signing queue. Archive it; it becomes deletable once all data ages out.

Payment

payment_required402

Subscription is past due. Update your payment method to continue using the API.

Rate Limiting & Quotas

rate_limited429

Request rate exceeds your plan limit. See Retry-After header.

quota_exceeded429

Monthly usage quota reached for this resource. Upgrade your plan.

too_many_orgs403

You've reached your plan's limit on audit organizations. Delete an unused org or upgrade your plan for more.

Server

db_error500

Database operation failed. Safe to retry with backoff.

ingest_failed500

Failed to persist the record. Safe to retry.

serialization_failed500

Internal serialization error. Contact support if persistent.

Rate-limit headers

Every API response includes standard rate-limit headers. When a 429 is returned the Retry-After header tells you exactly how many seconds to wait before retrying.

Retry-AfterSeconds to wait before retrying (present on 429 responses).

X-RateLimit-LimitMaximum requests per second for your plan tier.

X-RateLimit-RemainingRequests remaining in the current window.

Retry guidance

400 errorsDo not retry. Fix the request before resending.

401 / 403 errorsDo not retry. Check your API key, scopes, and IP allowlist.

404 errorsDo not retry. The resource does not exist.

409 errorsDo not retry writes. The existing record is returned in the response body.

413 errorsDo not retry. Reduce the payload size before resending.

429 errorsRetry after the number of seconds in the Retry-After header.

500 errorsRetry with exponential backoff. Contact support if persistent.

{ "error": "rate_limited", "message": "Rate limit exceeded for your plan (builder: 50 req/sec).", "retry_after": 2, "plan_tier": "builder", "limit_per_sec": 50, "upgrade_url": "/dashboard/plans/upgrade" }

{ "error": "quota_exceeded", "message": "You've reached your monthly events limit (10000/10000).", "resource": "events", "current_usage": 10000, "plan_limit": 10000, "plan_tier": "builder", "upgrade_url": "/dashboard/plans/upgrade" }