Error catalogue

Errors are RFC 9457 problem details (application/problem+json). Match on code; the title is safe to show to users and may be reworded.

Format

Problem details{
  "type": "https://mutualtrust.io/problems/validation_failed",
  "title": "The request body does not match the command schema.",
  "status": 422,
  "code": "validation_failed",
  "instance": "/v1/services",
  "request_id": "req_8e1f3a9c2b7d4e60",
  "errors": [
    {
      "path": "/route_templates/0/path",
      "message": "String does not match pattern"
    }
  ]
}

Every problem has request_id, also sent as X-Request-Id. 429 responses carry Retry-After; 503 responses carry Retry-After: 5.

Authentication and authorization

Authentication errors
Status	Code	Meaning
401	`unauthenticated`	No valid session or credential; or an OIDC token failed verification.
401	`attestation_invalid`	Enrollment attestation invalid: sandbox token unknown, expired or used; workload unknown; workload issuer not approved.
403	`forbidden`	Authenticated but not allowed: missing role, missing or wrong CSRF token, sandbox guest attempting production, credential minting from a credential, or creating a production space without production access.
403	`production_onboarding_incomplete`	Production spaces and services need a verified domain, approved production access and an active entitlement (subscription or approved invoice terms). `missing` lists what is outstanding; see production onboarding.
403	`production_access_required`	Production trust spaces are provisioned by Sectigo PKI Operations once your organization is ready.
403	`high_risk_credential_required`	An API credential without `high_risk_allowed` tried a high-risk change. Use a recently re-authenticated browser session, or a credential created with the flag (see step-up).
404	`not_found`	Does not exist, or belongs to an organization you are not a member of. Also returned for a failed renewal or reload proof.

Request and concurrency

Request errors
Status	Code	Meaning
409	`idempotency_key_reused`	The Idempotency-Key was used with a different body.
409	`invalid_transition`	The state machine does not allow this change (body includes `from` and `to`).
412	`revision_mismatch`	Stale `If-Match`; re-read and retry.
415	`unsupported_media_type`	Body sent without `Content-Type: application/json`.
422	`validation_failed`	Body failed the command schema or a domain rule (scope outside templates, bad CSR, bad proof, clock skew). See `errors[]`.
428	`idempotency_key_required`	This operation requires an Idempotency-Key.
428	`precondition_required`	This operation requires If-Match.
429	`rate_limited`	Too many requests; wait `Retry-After` seconds.
500	`internal`	Unexpected error. Quote the request ID.

Resources and lifecycle

Lifecycle conflicts
Status	Code	Meaning
409	`space_exists`	A space with that name exists in that environment.
409	`space_not_provisioned`	The space has no trust anchor yet.
409	`service_exists`	A service with that name exists in the space.
409	`invitation_not_pending`	The invitation was already accepted, declined, canceled, or lost a race.
409	`invitation_expired`	The invitation expired.
409	`capacity_exceeded`	No remaining production connections on the sponsor’s plan.
409	`last_owner`	The change would leave the organization without an owner. Make another member an owner first.
409	`grant_not_active`	The grant is not active; enrollment, renewal and issuance are blocked.
409	`grant_expiring`	The grant expires too soon to issue a certificate.
409	`attestation_replayed`	An enrollment token was redeemed concurrently.
409	`enrollment_used`	The enrollment challenge was already used.
409	`challenge_expired`	The enrollment challenge expired (5 minutes).
409	`serial_collision`	Serial collision during issuance; retry.
409	`issuance_refused`	The signer refused the issuance intent (code in the title).
409	`issuance_failed`	A previous attempt for this issuance request failed; start a new enrollment.
409	`certificate_revoked`	Renewal of a revoked certificate.
409	`certificate_expired`	Renewal of an expired certificate; re-enroll.
409	`already_revoked`	The certificate is already revoked.
409	`subscription_exists`	The organization already has a subscription; use the billing portal.
409	`stripe_error`	Stripe rejected the request.
409	`mcp_request_used`	This MCP connection request was already approved.
409	`domain_exists`	Your organization already added this domain.
409	`domain_limit`	Your organization has 10 domains. Remove one before adding another.
409	`verification_open`	A legal-entity verification is already awaiting review.
409	`origin_check_closed`	The origin check already has a result or has expired (one hour). Start a new check.
422	`origin_check_signature_invalid`	The origin check result signature does not verify with the check token.

Integration adapters

Integration adapter errors
Status	Code	Meaning
422	`adapter_unknown`	The adapter id or version is not in the adapter catalog.
409	`integration_exists`	This organization already has an integration for that adapter and endpoint in that environment.
422	`integration_scope_invalid`	The space, service or partner connection is not this organization’s, or is in another environment.
409	`integration_disabled`	The integration is disabled; plans, approvals and runs are refused.
422	`plan_target_mismatch`	The plan or run names another tenant, integration, adapter, endpoint or version.
422	`plan_hash_mismatch`	The plan was modified after mt-adapt sealed it.
409	`desired_state_mismatch`	The plan was computed against an older desired state. Fetch it again and plan again.
403	`step_up_required`	Approving needs a sign-in or passkey confirmation from the last 15 minutes (or less, when an approval policy says so; see `max_age_seconds`). Relaxing a production approval policy and every other high-risk change needs one too; `high_risk_action` names the change.
403	`second_approver_required`	You submitted this plan, or created the invitation behind this pending grant; another service owner or trust administrator must approve it.
403	`approver_too_new`	The approval policy needs an approver who has been a member for longer (`min_age_hours`). See Approval policies.
422	`approval_policy_below_floor`	An approval policy value is looser than the floor an enclosing scope sets; `fields[]` names each value, its floor and where the floor comes from.
409	`approval_unavailable`	The plan is still awaiting approval, or it was rejected.
409	`approval_expired`	The 24-hour approval window ended. Plan and approve again.
409	`approval_stale`	The desired state changed after approval. Plan and approve again.
409	`plan_not_approved`	An apply or rollback run must reference an approved plan of this integration.
503	`sso_secret_store_unconfigured`	The deployment cannot seal or open identity provider client secrets. Use a public client (PKCE only) or retry later.
409	`sso_domain_claimed`	One of the domains already routes to another organization identity provider.
409	`sso_not_tested`	Sign in once through the identity provider before enforcing SSO-only sign-in; the person enabling it must keep access.
409	`sso_break_glass_required`	SSO-only sign-in needs at least one break-glass owner who keeps passkey sign-in.
409	`sso_break_glass_limit`	The organization already has five break-glass owners.
409	`scim_token_limit`	The organization already has five active SCIM tokens. Revoke one first.
409	`owner_recovery_open`	An owner recovery for this organization is already open.
409	`owner_recovery_evidence_missing`	Staff only: the owner recovery has no fresh, verified DNS TXT challenge yet.
409	`delegation_open`	Staff only: an open delegation between these organizations already exists.
409	`payer_account_missing`	Staff only: the reseller has no billing account in that Stripe mode yet.
403	`support_case_required`	Staff only: support sees tenant details only with an open case assigned to them or a customer-approved support grant.

Dependencies

Dependency errors
Status	Code	Meaning
503	`signer_unavailable`	The signing service is unavailable. Existing certificates keep working.
503	`provider_timeout`	Signing provider timeout (never falls back to software).
503	`provider_unavailable`	Signing provider unavailable.
503	`provider_quota`	Signing provider quota exceeded.
503	`provider_key_disabled`	The signing key version is disabled.
503	`provider_key_not_found`	The signing key version is unknown or not allowlisted.
503	`provider_invalid_encoding`	The provider response failed integrity checks.
503	`issuer_unavailable`	The issuing CA is suspended.
503	`signature_verification_failed`	A signed certificate failed independent verification; retry.
503	`serial_mismatch`	A signed certificate did not match the approved intent.
503	`policy_not_published`	No policy revision exists yet for the gateway’s service.
503	`jwks_unavailable`	Could not fetch keys from the approved workload issuer.
503	`idp_unavailable`	The organization identity provider is unavailable.
503	`idp_issuer_mismatch`	The identity provider’s discovery document names a different issuer.
503	`oidc_unconfigured`	Organization sign-in is not configured on this deployment.
503	`billing_unconfigured`	Billing is not configured on this deployment.
503	`billing_misconfigured`	Live Stripe keys outside production.
503	`plan_unavailable`	That capacity band is not available for purchase.
503	`stripe_unavailable`	Stripe is unavailable or rate limiting.
503	`mcp_unconfigured`	The MCP server is not configured on this deployment.

Webhook responses

POST /webhooks/stripe answers Stripe directly: 400 {"code":"invalid_signature"} when the signature or timestamp fails, and 200 {"ignored":"mode_mismatch"} for events from the other Stripe mode.

Gateway deny codes

Gateways return 403 problem documents with their own codes: uninitialized, manifest_expired, no_client_certificate, tls_verification_failed, unknown_issuer, malformed_san, missing_client_auth_eku, certificate_expired, certificate_revoked, grant_revoked, grant_suspended, grant_expired, no_matching_grant, route_not_permitted, ambiguous_route, plus 502 origin_unavailable. Causes and fixes: Troubleshooting.