Error Codes Reference -- HTTP Status Codes, Diagnosis, and Resolution

Who this is for: Developers debugging API integration issues, DevOps engineers investigating pipeline failures, and anyone receiving an error response from the SWT3 API.

1. Error Response Format

All error responses follow this shape:

{
  "error": "Human-readable error message",
  "reference": "AXM-4821"   // Only present on 502/503 errors
}

AXM-XXXX Reference Codes

When you receive a 502 or 503 error, the response includes a unique reference code (e.g., AXM-4821). This code is logged server-side and links to internal diagnostics. Include it when contacting support for immediate correlation -- no guesswork required.

The error field always contains a human-readable description. For non-admin callers, sensitive details (database errors, stack traces, file paths) are sanitized and replaced with safe category messages.

2. HTTP Status Code Reference

Code	Name	Retryable	Description
400	Bad Request	No	Malformed JSON, missing required fields, invalid field values. The error message specifies which field failed validation.
401	Unauthorized	No	Missing or invalid authentication. No `Authorization: Bearer` header, key does not start with `axm_`, or key not found in database.
403	Forbidden	No	Authentication succeeded but access denied. Insufficient tier, wrong role (assessor attempting write), or revoked agent.
404	Not Found	No	Resource does not exist. Invalid audit token, unknown key ID, or no matching record.
409	Conflict	No	Duplicate entity. Email already registered, maximum webhook subscriptions reached, or duplicate API key.
422	Unprocessable	No	Request is syntactically valid but semantically wrong. Unknown procedure ID, clearing level out of range, timestamp out of bounds, fingerprint mismatch.
429	Rate Limited	Yes	Per-second or monthly limit exceeded. Check `Retry-After` header for wait time in seconds.
502	Upstream Error	Yes	Database write failed or external service timeout. Transient. Includes AXM-XXXX reference code. Wait 5-10 seconds and retry.
503	Service Degraded	Yes	Dependency unavailable (maintenance, overload). Includes AXM-XXXX code. Retry after 30 seconds.
506	Agent Revoked	No	The agent_id in the payload was revoked via AI-REV.1. Re-register the agent or use a different agent_id.

Example Responses

401 -- Missing Auth

HTTP/1.1 401 Unauthorized

{ "error": "Missing Authorization: Bearer <token> header" }

429 -- Rate Limited

HTTP/1.1 429 Too Many Requests
Retry-After: 2

{ "error": "Rate limit exceeded. Retry after 2s.", "retry_after_seconds": 2 }

502 -- Upstream Error

HTTP/1.1 502 Bad Gateway

// Non-admin caller:
{ "error": "A data service error occurred", "reference": "AXM-4821" }

// Admin/Bearer caller:
{ "error": "evidence ledger query timeout...", "reference": "AXM-4821" }

3. Diagnosis by Symptom

"My request is rejected" (400 / 401 / 403 / 422)

Getting 400 or 422?

The error message tells you exactly what is wrong. Check these in order:

Is the request body valid JSON? (Content-Type: application/json required)
Are all required fields present? (procedure_id, factor_a, factor_b, factor_c, clearing_level, anchor_fingerprint, anchor_epoch, fingerprint_timestamp_ms)
Is the procedure_id recognized? Check the UCT Registry for valid IDs.
Is clearing_level between 0 and 3?
Is the timestamp within bounds? (last 24 hours, no more than 5 minutes in the future)
Does the fingerprint match the factors? See Section 4.

Getting 401?

"Missing Authorization: Bearer <token> header" -- Add the header. Note: capital "B" in Bearer, followed by a space, then your key.
"Invalid token format -- must start with axm_" -- Your key does not have the correct prefix. Check for copy-paste errors.
"Invalid or revoked API key" -- The key hash does not match any record. The key may have been revoked, or you may have extra whitespace. Generate a new key at Settings > API Keys.

Getting 403?

"Enclave tier required" -- This feature (webhooks, VC export) requires Enclave ($9,500/mo) or higher. Your current tier does not include it.
"Admin only" -- This action requires the admin role. Check your role at Settings.
"Assessor mode is read-only" -- Assessors cannot create, modify, or delete resources. Use an admin account for write operations.
"Agent {id} has been revoked" -- The agent_id was revoked via AI-REV.1. Re-register the agent or remove the agent_id from the payload.

"My request is rate limited" (429)

Per-second limit vs monthly limit

Two distinct 429 scenarios:

Per-second limit: Message includes "Retry after Xs". Wait the specified time and retry. Implement exponential backoff.
Monthly limit: Message includes "Monthly anchor limit reached (100)". This is OPEN tier only. Upgrade to Pro for unlimited anchors. Counter resets on the 1st of each month (UTC).

See the Rate Limits and Quotas Guide for optimization strategies.

"My request failed server-side" (502 / 503)

Transient vs persistent failures

Transient (most cases): Wait 5-10 seconds and retry. Database connections, external service timeouts, and brief overloads resolve automatically.

Persistent (rare): If 502/503 errors persist for more than 5 minutes:

Check the health endpoint: curl https://sovereign.tenova.io/api/v1/health
If supabase: false, the database is degraded. Wait for recovery.
If health returns 200 but your requests fail, email support@tenovaai.com with the AXM-XXXX reference code.

"My agent is blocked" (506)

Agent revocation (506)

HTTP 506 means the agent_id in your witness payload has been revoked. This is intentional -- someone in your organization revoked this agent via the AI-REV.1 procedure.

Resolution:

Check who revoked the agent and why (Settings > Audit Log).
If the revocation was in error, re-register the agent via POST /api/v1/agents.
If the revocation was intentional, update your application to use a different agent_id.

4. Witness Validation Errors

These are the exact error messages returned by POST /api/v1/witness with the specific fix for each:

Error Message	Cause	Fix
`"Unknown AI procedure: AI-FOO.1"`	Procedure ID not in the recognized set (266 procedures)	Check the UCT Registry for valid IDs. Common typo: missing the "AI-" prefix.
`"clearing_level must be 0-3"`	Value is negative, greater than 3, or not a number	Use integer 0, 1, 2, or 3. Most integrations should use 1 (Standard).
`"Anchor timestamp out of bounds"`	`fingerprint_timestamp_ms` is more than 24h in the past or more than 5 min in the future	Sync your system clock via NTP. Ensure you are using milliseconds (not seconds). Example: `1786624093000` not `1786624093`.
`"Anchor fingerprint validation failed"`	The server re-derived the fingerprint from the factors and it does not match `anchor_fingerprint`	Something modified the request body between the SDK and the server (proxy, middleware, JSON serialization). Verify no middleware alters numeric fields (e.g., converting integers to floats). Test with `echo -n "WITNESS:{tenant}:{proc}:{fa}:{fb}:{fc}:{ts_ms}" \| sha256sum \| cut -c1-12`.
`"Payload signature validation failed"`	HMAC-SHA256 of the fingerprint does not match any registered signing key	Check: (1) correct signing_key_id, (2) correct secret, (3) key is registered server-side. If using key rotation, ensure the old key is still registered until migration is complete.
`"Invalid lifecycle_chain_id format"`	Must match `LC-[0-9a-f]{16}`	Format: "LC-" prefix followed by exactly 16 lowercase hex characters. Example: `LC-a1b2c3d4e5f67890`.
`"Invalid lifecycle_stage"`	Must be one of the 6 valid stages	Valid values: initiated, checkpoint, escalated, resolved, abandoned, superseded.
`"Invalid lifecycle_parent format"`	Must be exactly 12 lowercase hex characters	This is a fingerprint from a previous anchor. It must be 12 hex chars, not the full SWT3 token.

5. Admin vs Non-Admin Error Visibility

The API returns different levels of detail depending on the caller:

Caller Type	Error Detail	Example
Admin (session) or Bearer token	Full diagnostics including database error messages and context	`"evidence ledger query timeout after 30000ms"`
Non-admin (session)	Safe category message only	`"A data service error occurred"`
Assessor (session)	Safe category message + AXM reference code	`"A data service error occurred (ref: AXM-4821)"`

This prevents information disclosure (SI-11 compliance). Non-admin users never see database connection strings, file system paths, or stack traces.

Tip: If you receive a sanitized error message and need more detail, check the AXM-XXXX reference code in the response and include it when contacting support. The server-side logs contain the full diagnostic linked to that code.

6. Contacting Support

If you cannot resolve the error using this reference, email support@tenovaai.com with:

Tenant ID (shown in Settings)
Endpoint you are calling (e.g., POST /api/v1/witness)
Full error response (copy the entire JSON body)
AXM-XXXX reference code (if present)
SDK version (pip show swt3-ai or npm list @tenova/swt3-ai)
Timestamp of the error (UTC)

This eliminates the first round of back-and-forth and gets you to resolution faster.