Error catalog¶

Every Nanorix API error response follows the same JSON envelope. The machine-readable code is the canonical identifier — link to the per-error page below for resolution paths.

Response envelope¶

{
  "error": {
    "type": "<category>",
    "code": "<machine_code>",
    "message": "<human>",
    "doc_url": "https://docs.nanorix.io/errors/<code>",
    "request_id": "req_018f5b8e-3a9c-4c4d-9e7e-d4a8f7b2c10e",
    "retry_after": 30
  }
}

request_id is server-generated per request; copy it into support tickets so engineering can grep server logs cross-referenced. Also emitted in the X-Nanorix-Request-Id response header on every response (success or error).

Codes¶

code	http	type	plain-English cause	suggested resolution	severity
`invalid_api_key`	401	authentication_error	API key missing, malformed, or revoked	Verify key starts with `nrx_live_` or `nrx_test_`. Get key in your Console (Settings → API keys).	high
`resource_not_found`	404	not_found	Capsule, Capsulefile, proof, profile, or other resource ID does not exist or you don't have access	Check the resource ID. For destroyed capsules, use `GET /v1/proofs/<id>` instead.	medium
`invalid_parameters`	400	invalid_request_error	Request body malformed, missing required field, or field value out of range	Inspect `message` for the specific field; consult the API reference.	low
`rate_limited`	429	rate_limit_error	Per-IP or per-customer request rate exceeded	Wait `retry_after` seconds and retry. Use exponential backoff.	low
`quota_exceeded`	402	quota_error	Tier quota for AuditProofs / Capsulefile count / concurrent capsules reached	Upgrade tier in your Console (Billing) or wait for monthly reset.	medium
`resource_conflict`	409	conflict_error	Resource state conflict (duplicate name, capsule already destroyed, profile in use)	Inspect `message` for the conflict; resolve and retry.	low
`payload_too_large`	413	invalid_request_error	Request body / file upload exceeds tier limit	Compress or split the upload.	low
`capsule_expired`	410	capsule_error	Capsule has been destroyed (TTL elapsed or explicit destroy)	Use `GET /v1/proofs/<capsule_id>` to retrieve the AuditRecord. Capsule data is unrecoverable by design.	low
`mfa_required`	403	mfa_required	Endpoint requires recent MFA verification	Re-authenticate via MFA flow; retry within session window.	low
`mfa_enrollment_required`	403	mfa_enrollment_required	Paid tier requires MFA enrollment	Enroll MFA in your Console (Settings → Security).	medium
`tier_required`	403	forbidden	Endpoint requires Team tier or higher (e.g., egress profiles)	Upgrade tier or use a tier-eligible endpoint.	medium
`input_provenance_rejected`	422	input_provenance_error	Customer-declared input manifest hash does not match received bytes	Recompute the manifest hash on the source bytes; verify your signing key. Capsule has self-destroyed; rejection is in the AuditProof.	high
`secrets_injection_rejected`	422	secrets_injection_error	Customer-declared env_var secret could not be resolved	Verify the secret ID and your KMS configuration. Capsule has self-destroyed.	high
`internal_error`	500	api_error	Unexpected server-side failure	Reference the `request_id` to support@nanorix.io. Retry with backoff if transient.	high
`service_unavailable`	503	service_unavailable_error	Temporary downstream unavailability	Retry with backoff.	low

Severity rubric: high = customer cannot proceed; medium = customer may need to upgrade or reconfigure; low = customer-side fix in seconds.

invalid_api_key¶

HTTP 401 · authentication_error

Your API key is missing, malformed, or revoked.

Resolution¶

Confirm the key prefix: nrx_live_ for live use, nrx_test_ for test mode.
If the key looks correct, regenerate in your Console (Settings → API keys).
SDKs auto-load NANORIX_API_KEY env var; verify it's exported.

resource_not_found¶

HTTP 404 · not_found

The capsule, Capsulefile, proof, or profile ID you referenced doesn't exist (or you don't have access).

Resolution¶

Verify the resource ID (cap_, cf_, prf_*, etc.).
For destroyed capsules: use GET /v1/proofs/<capsule_id> to retrieve the AuditRecord. Capsule data itself is unrecoverable.
For shared resources: confirm your API key has access (check tier + org membership).

invalid_parameters¶

HTTP 400 · invalid_request_error

Request body is malformed, missing a required field, or a field value is out of range.

Resolution¶

The message field names the specific field that failed validation. Cross-reference the API reference for the endpoint's schema.

rate_limited¶

HTTP 429 · rate_limit_error

Per-IP or per-customer request rate exceeded.

Resolution¶

Wait retry_after seconds (returned in the response body and Retry-After header) and retry. Use exponential backoff for repeated 429s — both Nanorix SDKs do this automatically.

quota_exceeded¶

HTTP 402 · quota_error

You hit your tier's monthly cap for AuditProofs, Capsulefile count, or concurrent capsules.

Resolution¶

Upgrade tier in your Console (Billing).
Or wait for monthly reset (cycle starts on tier-upgrade anniversary).

resource_conflict¶

HTTP 409 · conflict_error

Resource state conflict — duplicate name, capsule already destroyed, profile referenced by active capsules, etc.

Resolution¶

The message field names the specific conflict. Common cases:

Duplicate Capsulefile name: rename or delete the existing one.
Capsule already destroyed: use GET /v1/proofs/<id> for the proof.
Egress profile in use: wait for active capsules to destroy or move them to a different profile.

payload_too_large¶

HTTP 413 · invalid_request_error

Request body or file upload exceeds your tier's limit.

Resolution¶

Split or compress the upload. Bundle uploads via nanorix build (gzipped tarball) compress aggressively for typical Capsulefiles.

capsule_expired¶

HTTP 410 · capsule_error

The capsule has been destroyed (TTL elapsed or explicit DELETE /v1/capsules/<id>).

Resolution¶

Capsule data is unrecoverable by design. Use GET /v1/proofs/<capsule_id> to retrieve the AuditRecord. The record carries the activity trail + cryptographic destruction evidence.

mfa_required¶

HTTP 403 · mfa_required

The endpoint requires recent MFA verification.

Resolution¶

Re-authenticate through your MFA flow. Sessions remain MFA-elevated for a short window.

mfa_enrollment_required¶

HTTP 403 · mfa_enrollment_required

Paid-tier accounts must have MFA enrolled.

Resolution¶

Enroll in your Console (Settings → Security). MFA enrollment is one-time; subsequent sessions just need verification.

tier_required¶

HTTP 403 · forbidden

The endpoint requires a higher tier (commonly Team and above, for egress profiles).

Resolution¶

Upgrade in your Console (Billing) or use a tier-eligible alternative endpoint.

input_provenance_rejected¶

HTTP 422 · input_provenance_error

The customer-declared input manifest hash doesn't match the bytes the runtime observed (or the manifest signature failed to verify).

Resolution¶

Recompute the input manifest hash on the source bytes.
Verify your signing key matches what the capsulefile declares.
The capsule has already self-destroyed; the rejection event is recorded in the AuditProof.

The error response includes:

reason — typed enum: hash_mismatch, signature_invalid, key_unknown
input_hash — the runtime-observed hash for cross-comparison

except InputProvenanceRejectedError as e:
    print(f"manifest mismatch: reason={e.reason}, runtime_hash={e.input_hash}")

secrets_injection_rejected¶

HTTP 422 · secrets_injection_error

A customer-declared env_var secret could not be resolved.

Resolution¶

The error response includes:

reason — typed enum: secret_not_found, decryption_failed, kms_unavailable
secret_id — the secret that failed

Customer self-resolution paths:

except SecretsInjectionRejectedError as e:
    if e.reason == "secret_not_found":
        rotate_secret(e.secret_id)
    elif e.reason == "decryption_failed":
        alert_security_team(e.secret_id)

The capsule has already self-destroyed; the rejection event is in the AuditProof.

internal_error¶

HTTP 500 · api_error

Unexpected server-side failure. Nanorix's monitoring will alert engineering.

Resolution¶

Note the request_id from the error body or X-Nanorix-Request-Id header.
Email support@nanorix.io with the request_id for fast triage.
Retry with exponential backoff if the failure is transient (network, DB hiccup, etc.). SDKs auto-retry 5xx by default.

service_unavailable¶

HTTP 503 · service_unavailable_error

Temporary downstream unavailability.

Resolution¶

Retry with exponential backoff. SDKs auto-retry 5xx by default; honour retry_after when present.