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.

Authorization

insufficient_scope403

API key lacks the required scope (read or 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.

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.

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.

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.

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.

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