Skip to main content

Errors and versioning

Launch errors​

Every launch failure is a 303 to {MURMLE}/launch/error?reason=<message>, except rate limiting, which is a 429. The messages are written for the person in front of the browser, and they deliberately do not say which check failed when that would help a forger.

MessageCauseWhat to do
Invalid launch tokenNot a parseable JWT, or no iss.Fix the minting code.
Unknown launch issueriss matches no registered integration.Check iss against the registered issuer, character for character.
This integration is not activeThe integration is disabled or awaiting approval.Ask the workspace's owner or admin.
This launch link is not validSignature, alg, kid, aud, iss, exp/nbf, or a required claim failed. One message for all of them, by design.Check the key, the audience, the clock and the claims.
This launch link has already been usedThe jti was accepted before.Mint a new token per launch; never reuse or retry one.
This launch uses an integration contract version Murmle does not supportcontract_version is not "1".Send "1" or omit it.
The launch token does not say which activity to openNeither resource_id nor context.activity_id.Add resource_id.
That activity is not linked to a Murmle activity yetNo link for this resource_id.Ask for the resource to be linked.
Publish the activity before running a sessionThe linked activity has never been published, and a new run was needed.Ask the activity's creator to publish it.
The identity provider did not supply an email addressAn instructor launch without email.Send email for instructors.
Your email address already has a Murmle account that is not part of this workspace...An instructor launch whose email belongs to an account outside the workspace.The account must already be an active member of the workspace - for example through the workspace's single sign-on or directory provisioning - before an instructor launch can use it.

A launch can also be refused because the activity contains a question that is not allowed in the run's privacy mode - for example a contact-details question in an anonymous run. The message says which rule applies.

Webhooks (you to Murmle)​

Your response code is the whole protocol: 2xx means processed or deliberately ignored; anything else means retry. Murmle does not read your response body.

API errors​

The REST API and the admin API return JSON with a detail field:

  • 422 - a request that is malformed or breaks a rule. Schema failures carry a list in detail; rule failures carry one readable sentence.
  • 401 - no credential, or one that is unknown, wrong or revoked. These are deliberately not distinguished.
  • 403 - the credential is valid but lacks the scope or role; the detail names what is missing.
  • 404 - not found, or not visible to this credential.
  • 409 - a valid request at the wrong moment: an issuer already registered, a secret already collected, an integration awaiting approval.
  • 429 - rate limited.

Versioning policy​

  • This is contract version 1. A launch token MAY say so with "contract_version": "1"; one that does not is read as v1.
  • Additive changes are not a new version: a new optional claim, a new event type, a new field in an event's data, a new optional registration field. Consumers MUST ignore event types and fields they do not recognise, and acknowledge such events with a 2xx.
  • A breaking change is a new version - removing or renaming a claim or field, changing a type or a meaning, changing the signature scheme. It would be published as v2, and Murmle would accept v1 alongside it; a token would select v2 by sending "contract_version": "2". v1 is retired only after a notice period announced in the contract.
  • Deprecated names stay accepted within a version. The legacy context.activity_id / context.course_id aliases and the pamba integration type are deprecated, not removed.
  • Changes to the contract are listed in the release notes.