{"record":{"id":"4512552e9b148a5d","repo":"stablyai/orca","slug":"response-error-code-response-error-message","errorCode":null,"errorMessage":"${response.error.code}: ${response.error.message}","messagePattern":"\\$\\{response\\.error\\.code\\}: \\$\\{response\\.error\\.message\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"mobile/src/transport/mobile-relay-credential-rotation.ts","lineNumber":57,"sourceCode":"    })\n    // Why: a crash or lost response must leave enough material to query the\n    // one global install key before any second authorization attempt.\n    await args.writeBundle(bundle)\n  }\n\n  const pending = bundle.pending\n  if (!pending) {\n    throw new Error('relay credential rotation pending state missing')\n  }\n  let endpoints = await getEndpoints(args.client, pending.reqId)\n  if (endpoints.installStatus?.state !== 'committed') {\n    const response = await args.client.sendRequest('pairing.provisionRelay', {\n      reqId: pending.reqId,\n      newResumeTokenHash: pending.hash,\n      expectedCurrentHash: bundle.current.hash\n    })\n    if (!response.ok) {\n      throw new Error(`${response.error.code}: ${response.error.message}`)\n    }\n    const installed = DeviceCredentialInstalledSchema.parse(response.result)\n    endpoints = await getEndpoints(args.client, pending.reqId)\n    if (\n      endpoints.installStatus?.state !== 'committed' ||\n      JSON.stringify(endpoints.installStatus.result) !== JSON.stringify(installed)\n    ) {\n      throw new Error('relay credential rotation was not authoritatively committed')\n    }\n  }\n  if (!endpoints.relay || endpoints.installStatus?.state !== 'committed') {\n    throw new Error('relay credential rotation endpoint state missing')\n  }\n  const installed = endpoints.installStatus.result\n  const next = MobileRelayCredentialBundleSchema.parse({\n    ...bundle,\n    current: {\n      token: pending.token,","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/mobile/src/transport/mobile-relay-credential-rotation.ts#L39-L75","documentation":"Thrown when the `pairing.provisionRelay` RPC returns `!response.ok` during credential rotation. The message is the server's own error code and message (e.g. `auth_failed: ...`), surfaced verbatim so the operator can see why the relay server refused to install the new resume token hash.","triggerScenarios":"Server rejected `provisionRelay` because `expectedCurrentHash` does not match the currently installed credential; the install `reqId` is unknown or already consumed; authorization failure on the device token; transient server error.","commonSituations":"Concurrent rotation attempts racing on the same `expectedCurrentHash`; a stale bundle whose `current.hash` was already superseded by another rotation; server restart that lost the pending install state.","solutions":["Re-read the credential bundle from disk and retry once — another rotation may have advanced `current`.","If the error code indicates `expected_current_hash_mismatch`, abandon the rotation and resync from pairing.","For transient server errors, retry with backoff bounded by the rotation window."],"exampleFix":"// before\ntry { await rotateMobileRelayCredential({ client, bundle, writeBundle }) }\ncatch (e) { throw e } // bubbles raw\n\n// after\ntry { return await rotateMobileRelayCredential({ client, bundle, writeBundle }) }\ncatch (e) {\n  if (e.message.startsWith('expected_current_hash_mismatch')) {\n    bundle = await readMobileRelayCredentialBundle(hostId) ?? bundle\n    return await rotateMobileRelayCredential({ client, bundle, writeBundle })\n  }\n  throw e\n}","handlingStrategy":"retry","validationCode":"// Refresh the bundle before rotation to reduce stale expectedCurrentHash:\nbundle = (await readMobileRelayCredentialBundle(hostId)) ?? bundle","typeGuard":"function isStaleHashError(e: unknown): boolean { return e instanceof Error && e.message.startsWith('expected_current_hash_mismatch') }","tryCatchPattern":"try { return await rotateMobileRelayCredential({ client, bundle, writeBundle }) } catch (e) { if (isStaleHashError(e)) { bundle = (await readMobileRelayCredentialBundle(hostId)) ?? bundle; return await rotateMobileRelayCredential({ client, bundle, writeBundle }) } throw e }","preventionTips":["Re-read the bundle before each rotation attempt.","Serialize rotation per host to avoid racing on expectedCurrentHash.","Retry only idempotent error codes; bail on authorization failures."],"tags":["relay","rpc","credentials","rotation","network"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}