HTTP status: transfer gates failed

This page documents the problem type URI returned when a transfer (moving an existing enrolment to another activity) is blocked after evaluating transfer rules and destination enrolment gates (including after applying any permitted staff_overrides).

Canonical problem type

type: "https://docs.keja.co/troubleshooting/status-codes/transfers.gates_failed"

Use this URI as the stable identifier for this failure class. Individual failures inside the document use errors[].code (see below).

HTTP mapping

Item	Value
Status code	`422`
Content-Type	`application/problem+json`
`title` (problem)	Short human label (for example "Transfer requirements not met").
`detail` (problem)	Human explanation; do not parse for automation per RFC 9457.

Problem document shape

Core RFC 9457 members plus an errors extension array (same multi-issue contract as other Cadence gate endpoints):

{
  "type": "https://docs.keja.co/troubleshooting/status-codes/transfers.gates_failed",
  "status": 422,
  "title": "Transfer requirements not met",
  "detail": "One or more rules blocks transferring this enrolment.",
  "instance": "/api/v1/activities/activities/enrollments/123/transfer/",
  "errors": [
    {
      "code": "transfers.disabled_for_category",
      "title": "Transfers disabled",
      "detail": "Transfers are disabled for activities in this category branch.",
      "severity": "blocking",
      "can_override": true,
      "required_permission": "activities.override_transfer_disabled",
      "pointer": null,
      "meta": {}
    }
  ]
}

`errors` items (normative)

Each element describes one gate outcome. Clients should rely on:

Field	Meaning
`code`	Stable machine id (dotted string), for example `enrollments.age_below_minimum`.
`title`	Short heading suitable for UI.
`detail`	Longer message; not a logic key.
`severity`	Typically `blocking` for failed gates; future severities may appear.
`can_override`	Whether staff may attest an override if they hold `required_permission`.
`required_permission`	Django permission codename required to override this `code`, or `null` if not overridable.
`pointer`	Optional JSON Pointer into the request (for example `#/family_id`).
`meta`	Structured context (policy ids, level ids, bounds); may be empty.

Transfer issue codes

transfers.disabled_for_category: Transfers are turned off for the destination category branch.
transfers.same_program_required: Destination category requires the same program as the source activity.
transfers.same_level_required: Destination category requires the same level as the source activity.
transfers.same_sport_required: Destination category requires the same sport as the source activity.
transfers.same_location_required: Destination category requires the same venue as the source activity.
transfers.source_not_allowlisted: Source category is not allowlisted for transfers into the destination.
transfers.outside_time_window: Transfer is outside the allowed lead time before the next session.
transfers.source_not_transferable: Source enrolment is not active, or not a transferable enrolment type.
transfers.same_activity: Destination is the same activity as the source.
transfers.target_session_not_found: No upcoming session found on the destination activity from the evaluation time.
transfers.cross_tenant: Destination activity belongs to another organisation.
transfers.target_not_found: Destination activity id was not found (also used for synthetic API errors).
transfers.source_not_found: Source enrolment row was not found under the lock (for example deleted).

Enrolment gates on the destination activity (capacity, age, policies, overlap, and similar) reuse the same enrollments.* codes documented on enrolments.gates_failed. Those entries appear in the same errors array when they apply to the destination.

For staff workflow when moving someone between activities, see Move an enrolment to another activity.

For developers and integrators

Preview (dry run): POST /api/v1/activities/activities/enrollments/{id}/transfer-evaluation/
Commit: POST /api/v1/activities/activities/enrollments/{id}/transfer/

OpenAPI is the normative source for request and response schemas.