hcengineering/platform · error · PlatformError

platform.status.InternalServerError

platform.status.InternalServerError

Error message

Internal server error

What it means

The integration client maps any HTTP 5xx response to PlatformError with status.InternalServerError and message 'Internal server error'. The server failed while processing a valid request; the client did nothing wrong.

Source

Thrown at packages/integration-client/src/request.ts:90

    try {
      return JSON.parse(text)
    } catch (error) {
      console.warn('Failed to parse JSON response:', text, error)
      return undefined
    }
  } else if (response.status === 202) {
    return undefined
  } else if (response.status === 401) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.Unauthorized, {}))
  } else if (response.status === 403) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.Forbidden, {}))
  } else if (response.status === 404) {
    throw new PlatformError(
      new Status(Severity.ERROR, platform.status.ResourceNotFound, { resource: options.path ?? '' })
    )
  } else if (response.status >= 500) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.InternalServerError, {}))
  } else {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.BadRequest, { status: response.status }))
  }
}

View on GitHub (pinned to 63e28dc964)

Solutions

1. Retry with exponential backoff — 5xx is often transient.
2. Inspect the integration service's server logs for the corresponding stack trace.
3. Check service health/status endpoint and recent deploys.
4. Escalate to the service owners if 5xx persists.

function isInternalServerError (err: unknown): err is PlatformError {
  return err instanceof PlatformError && (err.status.code as number) === platform.status.InternalServerError
}

try {
  return await client.request(...)
} catch (err) {
  if (isInternalServerError(err)) {
    return await retryWithBackoff(() => client.request(...), { retries: 3, baseDelayMs: 500 })
  }
  throw err
}

When it happens

Trigger: Any request() call where the integration service responds with status >= 500.

Common situations: Integration service crash or unhandled exception; downstream dependency of the service failing; deploy in progress; resource exhaustion on the server.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• err.message
• err.message
• rate-limit
• result.error
• No connection available

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