Errors & Status Codes

All error responses follow a consistent structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description of what went wrong.",
    "details": {}
  },
  "correlation_id": "uuid-for-support"
}

The correlation_id is included on every response and can be provided to MeshQu support for troubleshooting.

HTTP status codes

Status	Code constant	Meaning
`200`	—	Success.
`201`	—	Resource created.
`400`	`VALIDATION_ERROR`	Request body or query parameters failed validation. Check `details` for field-level errors.
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`403`	`FORBIDDEN`	API key lacks the required scope, or tenant ID does not match the key.
`404`	`NOT_FOUND`	Resource does not exist or is not accessible to this tenant.
`408`	`REQUEST_TIMEOUT`	Server-side processing exceeded the timeout.
`409`	`DUPLICATE_CODE`	A policy or group with this code already exists.
`429`	`TOO_MANY_REQUESTS`	Rate limit exceeded. See `rate-limit-*` headers and `retryAfter` in the body.
`500`	`INTERNAL_ERROR`	Unexpected server error.
`503`	`SERVICE_UNAVAILABLE`	A downstream dependency (e.g. database) is unreachable.

Domain-specific errors

These may appear in the code field for specific operations:

Code	Context	Meaning
`NO_ACTIVE_POLICIES`	Decision evaluation	No active policies matched the `decision_type`.
`NO_ACTIVE_RULES`	Decision evaluation	Policies exist but have no active rules.
`SNAPSHOT_NOT_FOUND`	Decision replay	The policy snapshot for this decision could not be located.
`HYDRATE_FAILED`	Decision replay / bundle export	The persisted decision could not be rehydrated into a verifiable form.
`ALREADY_DELIVERED`	Webhook retry	Delivery was already successful; cannot retry.
`STILL_PENDING`	Webhook retry	Delivery is still pending; no retry needed.
`CONFLICT`	Idempotency / unique constraints	A conflicting record already exists (e.g. duplicate idempotency key, duplicate outcome).

Tenancy

Code	Status	Meaning
`MISSING_TENANT_ID`	400	Required tenant header was not present on the request.
`INVALID_TENANT_ID`	400	Tenant header value is malformed or unknown.

Policy lifecycle

Code	Status	Meaning
`MAKER_CHECKER_VIOLATION`	403	The ratifier is the same user who created the version (when maker-checker is enforced via tenant settings).
`RATIFICATION_ERROR`	400	Version is not in the correct lifecycle state for this operation.
`NO_DRAFT`	404	Operation requires a `draft` version but none exists.
`NO_VERSIONS`	404	The policy has no versions.

Receipts, chains, and bundles

Code	Context	Meaning
`SIGNING_FAILED`	Decision record / chain seal	The configured signing key could not produce a signature.
`CHAIN_TOO_LARGE`	Chain operations	The chain exceeds the per-tenant size limit.
`BUNDLE_EXPORT_DISABLED`	Bundle endpoints	Bundle export is not enabled for this tenant.

Evidence manifest

Code	Status	Meaning
`EVIDENCE_MANIFEST_MALFORMED`	400	The submitted evidence manifest is not a valid manifest.
`EVIDENCE_DIGEST_MISMATCH`	400	A referenced evidence digest does not match the recomputed digest.
`EVIDENCE_MANIFEST_REFERENCED_BUT_MISSING`	400	The decision references an evidence manifest that was not supplied.
`EVIDENCE_MANIFEST_DIGEST_WITHOUT_FK`	400	An evidence manifest digest was submitted without a corresponding manifest record.

Policy approval receipts

Code	Status	Meaning
`POLICY_APPROVAL_RECEIPTS_MALFORMED`	400	The submitted approval receipts are not in the expected shape.
`APPROVAL_RECEIPTS_REFERENCED_BUT_MISSING`	400	The decision references approval receipts that were not supplied.
`RATIFIER_KEY_REQUIRED`	400	Approval receipt verification requires a ratifier public key that was not configured.

Handling errors in the SDK

The TypeScript SDK throws typed error classes:

import {
  MeshQuError,
  MeshQuValidationError,
  MeshQuAuthError,
  MeshQuForbiddenError,
  MeshQuNotFoundError,
  MeshQuConflictError,
  MeshQuRateLimitError,
  MeshQuNetworkError,
  MeshQuTimeoutError,
} from '@meshqu/client';

try {
  const result = await client.evaluate(context);
} catch (err) {
  if (err instanceof MeshQuRateLimitError) {
    // Back off and retry
  } else if (err instanceof MeshQuValidationError) {
    // Fix request payload
    console.error(err.message, err.details);
  } else if (err instanceof MeshQuAuthError) {
    // Check API key
  } else if (err instanceof MeshQuNetworkError) {
    // Network issue — retry with backoff
  }
}

Correlation IDs

Every response includes a correlation_id (also available as the x-correlation-id response header). Include this when contacting support.

Retry guidance

Error	Retry?	Strategy
`400`	No	Fix the request.
`401` / `403`	No	Check credentials and scopes.
`404`	No	Verify the resource ID.
`408`	Yes	Retry with same request.
`409`	No	Use a different code or check existing resources.
`429`	Yes	Wait for `Retry-After` seconds, then retry.
`500`	Yes	Retry with exponential backoff.
`503`	Yes	Retry with exponential backoff.

Getting Started

Concepts

API Reference

SDK

Guides

Recipes

Security

Meta

HTTP status codes

Domain-specific errors

Tenancy

Policy lifecycle

Receipts, chains, and bundles

Evidence manifest

Policy approval receipts

Handling errors in the SDK

Correlation IDs

Retry guidance

​HTTP status codes

​Domain-specific errors

​Tenancy

​Policy lifecycle

​Receipts, chains, and bundles

​Evidence manifest

​Policy approval receipts

​Handling errors in the SDK

​Correlation IDs

​Retry guidance

HTTP status codes

Domain-specific errors

Tenancy

Policy lifecycle

Receipts, chains, and bundles

Evidence manifest

Policy approval receipts

Handling errors in the SDK

Correlation IDs

Retry guidance