hcengineering/platform · error · PlatformError

${errorBody?.error}

Error message

${errorBody?.error}

What it means

sendRequest wraps all HTTP calls made by setValue/getValue/deleteKey/listKeys. When the server responds with a non-OK status and its JSON body contains an `error` field, the client re-throws that server-provided message wrapped in a PlatformError. This propagates the actual backend reason (auth failure, not found, quota, etc.) to the caller.

Source

Thrown at packages/kvs-client/src/client.ts:148

      ...this.requestInit,
      method: options.method,
      headers,
      body: options.body
    })

    if (options.returnNullOn404 === true && response.status === 404) {
      return null
    }

    if (options.acceptNotFound === true && response.status === 404) {
      return null
    }

    if (!response.ok) {
      try {
        const errorBody = await response.json()
        if (errorBody?.error != null) {
          throw new PlatformError(errorBody?.error)
        }
      } catch (e) {
        // Ignore JSON parsing errors
      }
      throw new Error(options.errorMessage ?? 'Request failed')
    }

    // Parse JSON response when needed
    const contentType = response.headers.get('content-type')
    if (
      response.status !== 204 &&
      (options.method === 'GET' || (contentType != null && contentType.includes('application/json')))
    ) {
      return await response.json()
    }

    return null
  }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Read the PlatformError message — it contains the server's own error description and usually states the exact cause.
2. Check that the token passed to the KvsClient constructor is valid and not expired.
3. Verify the namespace/key identifier used in the failing call exists on the server.
4. Wrap calls in try/catch and handle PlatformError distinctly from generic failures to react to server-reported conditions.

Example fix

// before
await client.getValue('user:42')
// after
try {
  await client.getValue('user:42')
} catch (e) {
  if (e instanceof PlatformError) console.error('Server said:', e.message)
  else throw e
}

if (!token) throw new Error('Refusing KVS call: token missing') // avoid predictable 401s before calling the API

function isPlatformError(e: unknown): e is PlatformError {
  return e instanceof PlatformError
}

try {
  await client.getValue(key)
} catch (e) {
  if (isPlatformError(e)) {
    // e.message is the server-provided reason; branch on it
  } else {
    throw e
  }
}

When it happens

Trigger: Any of setValue, getValue, deleteKey, or listKeys receiving an HTTP error response whose body parses as JSON with a non-null `error` property — e.g. 401 with `{"error":"unauthorized"}` or 404 with `{"error":"key not found"}`.

Common situations: Expired or invalid auth token, wrong namespace or key name, service-side rate limiting, or the server rejecting a malformed value.

Related errors

• Request failed
• ${error.error ?? text}
• Payment service error: ${response.status} ${text}
• err.message?.length > 0 ? err.message : 'Internal Server Err
• Export failed

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/65af5dd0d62f1079. Report an issue: GitHub.