Errors

All Admin API errors use one envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "request_id": "req_..."
  }
}

Current standard codes include missing_token, invalid_token, expired_token, rotated_token, insufficient_scope, suspended_application, deleted_application, not_found, validation_failed, member_already_exists, unsupported_media_type, payload_too_large, rate_limited, idempotency_conflict, idempotency_in_progress, and upstream_error.

validation_failed can be returned with 400 for invalid JSON or unsupported Accept headers, and with 422 for semantic validation errors such as invalid cursors or invalid resource attributes.

Space configuration and payment endpoints add domain-specific codes:

upgrade_required (422) — the change is gated to higher account tiers (the response includes required_permission and allowed_account_types).
payment_gate_managed_separately (422) — privacy cannot move to or from "payment" via PATCH /spaces/{space_id}; use PATCH /spaces/{space_id}/payment.
no_active_plans (422) — enabling paid access requires at least one active plan.
stripe_not_connected (422) — enabling paid access requires a charge-ready Stripe account.
live_enrollments (409) — disabling paid access while live enrollments exist requires force: true (the response includes live_enrollments).
mixed_plan_billing (422) — multiple plan selection requires all active plans to share one currency and one billing family; plan writes that would break this are rejected too.
guest_checkout_prerequisites (422) — guest checkout cannot be enabled while an active plan has prerequisites.
image_download_failed (422) — a space image could not be downloaded, validated, or processed from source_url.

Some plan responses also include a non-error warnings array (for example, writing plans while the payment gate is off). Warnings are advisory; the request succeeded.