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.
| Message | Cause | What to do |
|---|---|---|
| Invalid launch token | Not a parseable JWT, or no iss. | Fix the minting code. |
| Unknown launch issuer | iss matches no registered integration. | Check iss against the registered issuer, character for character. |
| This integration is not active | The integration is disabled or awaiting approval. | Ask the workspace's owner or admin. |
| This launch link is not valid | Signature, 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 used | The 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 support | contract_version is not "1". | Send "1" or omit it. |
| The launch token does not say which activity to open | Neither resource_id nor context.activity_id. | Add resource_id. |
| That activity is not linked to a Murmle activity yet | No link for this resource_id. | Ask for the resource to be linked. |
| Publish the activity before running a session | The 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 address | An 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 indetail; 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; thedetailnames 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 a2xx. - 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_idaliases and thepambaintegration type are deprecated, not removed. - Changes to the contract are listed in the release notes.